@nerdev/skillset 0.2.1

package/skills/ui/refero-design/references/example-workflow.md

@@ -0,0 +1,264 @@
+# Example Workflow: SaaS Pricing Page
+
+This walkthrough shows the expected shape of a Refero Design process. Replace the example
+references with actual results from the MCP during real work.
+
+Task: design a pricing page for **Northstar**, a B2B analytics product for operations teams.
+The page must feel trustworthy, precise, and modern without looking like a generic AI SaaS
+template.
+
+---
+
+## Phase 0: Discovery
+
+Brief:
+
+```text
+Designing a web pricing page for operations leaders and finance stakeholders.
+Goal: help qualified teams choose a plan or contact sales with confidence.
+Tone: precise, calm, credible, quietly premium.
+Main objection/risk: unclear ROI and fear of enterprise lock-in.
+Must remember: pricing feels transparent and tied to operational value.
+Constraints: existing product uses dense dashboards; avoid flashy gradients.
+Research needed: styles for visual language, screens for pricing structure, flows for upgrade/billing sequence.
+```
+
+---
+
+## Phase 1: Styles Research
+
+Start with styles because this is a visual/brand task.
+
+### Style Searches
+
+```text
+editorial monochrome SaaS landing page
+premium data infrastructure website restrained typography
+developer tool website with product screenshots
+productivity SaaS with airy spacing
+enterprise analytics product marketing
+```
+
+Open 3-4 strong styles with `refero_get_style`; full styles are large, so split larger
+research into multiple batches.
+
+### Style Findings
+
+| Reference | What It Contributes | What To Adapt |
+|-----------|---------------------|---------------|
+| Style A: editorial monochrome SaaS | Strong typographic hierarchy, low color, confidence through restraint | Use a mostly neutral palette and crisp type scale |
+| Style B: data infrastructure website | Dense technical credibility, grid structure, product screenshot framing | Use structured comparison tables and screenshot panels |
+| Style C: productivity SaaS | Airy spacing, friendly trust, softer supporting sections | Add breathing room around plan cards and proof sections |
+| Style D: premium fintech/product marketing | Subtle accent discipline, numbers presented with authority | Use exact ROI metrics and restrained accent color |
+
+### Visual Direction Synthesis
+
+Primary foundation: data infrastructure website.
+
+Borrowed details:
+
+- From editorial SaaS: tighter type hierarchy and low color discipline.
+- From productivity: more generous section spacing and softer proof blocks.
+- From premium fintech: accent color reserved for value proof and selected plan state.
+
+Reference lock:
+
+```text
+Primary reference/direction: data infrastructure website.
+Preserve: precise grid, compact comparison table, screenshot framing, sans-led UI,
+technical confidence, restrained neutral canvas.
+Borrow only: editorial type hierarchy, productivity spacing, fintech proof treatment.
+Role rules: green proof accent only for selected state/value proof; product screenshot
+frames only for evidence; cards use pricing-screen interaction rules, not decoration.
+Media strategy: real product screenshots when available; otherwise fixed-ratio screenshot
+placeholders with labels and art direction, not fake decorative app mockups.
+Reject: cream editorial canvas, serif hero, muted clay/orange accent, decorative cards.
+Token commitments: white/charcoal/cool-neutral canvas, sans typography, green proof
+accent, 8px max radius, thin borders, product screenshots as evidence.
+```
+
+Resulting direction:
+
+```text
+A precise, evidence-led pricing page: white canvas, deep charcoal text, compact sans-led
+headlines, thin rule lines, quiet plan cards, and exact operational metrics. Use one
+muted green accent for value proof and selected actions. Product screenshots should be
+framed as evidence, not decoration.
+```
+
+---
+
+## Phase 2: Screen Research
+
+Use screens for concrete pricing decisions after visual direction is clear.
+
+### Screen Searches
+
+```text
+pricing page annual monthly toggle
+feature comparison table SaaS pricing
+usage based pricing enterprise
+contact sales pricing page
+pricing page ROI calculator
+```
+
+Open the strongest screens with `refero_get_screen`. Use `refero_get_similar_screens` if
+one example is especially relevant.
+
+### Screen Findings
+
+| Pattern | What To Look For | Decision |
+|---------|------------------|----------|
+| Plan cards | Number of plans, highlighted plan, CTA hierarchy | Use 3 plans; highlight Pro as default |
+| Billing toggle | Placement, annual discount language, interaction clarity | Put monthly/annual toggle above cards; show exact annual savings |
+| Feature comparison | Whether comparison is complete or simplified | Use compact comparison under cards with expandable details |
+| Enterprise CTA | How sales motion is framed | Use "Talk to sales" for Enterprise with proof and security cues |
+| ROI proof | Placement of metrics/calculator | Add ROI strip between plan cards and comparison table |
+
+Concrete tactics to adapt:
+
+- Put "No credit card required" near the trial CTA, not buried in FAQ.
+- Show annual savings as exact value where possible, not just a percentage.
+- Make Enterprise feel like a tailored plan, not a vague catch-all.
+- Use a comparison table for evaluation buyers, but keep the first viewport decisive.
+- Include security/procurement signals near the Enterprise CTA.
+
+---
+
+## Phase 3: Flow Research
+
+Use flows because pricing can lead into upgrade, checkout, or sales contact journeys.
+
+### Flow Searches
+
+```text
+workspace billing upgrade
+checkout subscription SaaS
+contact sales pricing
+trial signup billing
+```
+
+Open relevant flows with `refero_get_flow`.
+
+### Flow Findings
+
+| Journey Question | Finding To Extract | Decision |
+|------------------|-------------------|----------|
+| What happens after plan selection? | Does the product ask for account, payment, or workspace first? | Trial CTA starts account creation before payment |
+| How is annual billing confirmed? | Are savings and renewal dates repeated? | Repeat billing period and savings in checkout |
+| How does sales contact work? | Is it calendar, form, or direct email? | Enterprise CTA opens short sales form with company size |
+| How are errors/recovery handled? | Can users return to pricing without losing state? | Keep selected plan visible through signup |
+
+---
+
+## Phase 4: Synthesis
+
+### Research Summary
+
+```text
+Research summary:
+- Styles reviewed: 5 across editorial SaaS, data infrastructure, productivity, fintech.
+- Screens reviewed: pricing cards, billing toggles, feature comparison, ROI proof, enterprise CTAs.
+- Flows reviewed: upgrade, checkout, sales contact.
+
+Visual direction:
+- Primary foundation: data infrastructure website.
+- Reference lock: precise grid, compact comparison, sans-led UI, product evidence.
+- Borrowed detail 1: editorial type hierarchy and low color discipline.
+- Borrowed detail 2: fintech-style precision around numbers and proof.
+
+Product patterns:
+- 3 plan cards with Pro highlighted.
+- Monthly/annual toggle above cards.
+- ROI proof strip before detailed comparison.
+- Enterprise CTA supported by security/procurement signals.
+
+Journey logic:
+- Trial starts account creation before payment.
+- Checkout repeats selected plan, billing period, savings, and renewal date.
+- Enterprise route asks only for essential qualification fields.
+```
+
+### Design Decision Ledger
+
+| Area | Decision | Source | Source rule / role | Why |
+|------|----------|--------|--------------------|-----|
+| Palette | White, charcoal, cool neutrals, muted green accent | Style B + fintech reference + brief | Accent only for value proof and selected actions | Trustworthy and precise; avoids generic blue/purple SaaS |
+| Typography | Sans-led hierarchy, tight headings, readable 15-16px body | Style B + Style A hierarchy | Use hierarchy, not decorative serif voice | Premium without becoming decorative or literary |
+| Layout | Precise grid, compact comparison structure, proof near decision points | Style B + pricing screens | Grid is the core layout rule, not generic stacked sections | Keeps the page scannable for evaluation buyers |
+| Media | Product screenshots as evidence panels | Style B + brief | Use real screenshots or labeled placeholders; no fake decorative mockups | Keeps proof honest without low-quality invented imagery |
+| Cards | Thin borders, subtle selected state, no heavy shadows | Pricing screens + anti-slop card rule | Cards only for plan comparison and interaction | Keeps evaluation calm and scannable |
+| CTA hierarchy | Pro trial primary, Enterprise sales secondary | Pricing screens + buyer journey | Primary treatment only for self-serve action | Supports self-serve and sales-led paths |
+| Proof | ROI metrics near pricing, security near Enterprise | Screen research + buyer objections | Proof modules near the decision they support | Answers buyer objections where they appear |
+| Memorable detail | "Operational value" strip showing saved hours/cost by plan | Brief + analytics product context | Metric strip as evidence, not decoration | Makes pricing feel tied to outcome |
+
+---
+
+## Phase 5: Implementation Blueprint
+
+### Tokens
+
+```css
+:root {
+  --font-sans: "Inter", system-ui, sans-serif;
+  --color-bg: #ffffff;
+  --color-text: #171717;
+  --color-muted: #6b7280;
+  --color-line: #e5e7eb;
+  --color-accent: #1f8a5b;
+  --color-accent-soft: #e8f5ee;
+  --radius-card: 8px;
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --space-16: 64px;
+}
+```
+
+### Page Structure
+
+```text
+1. Pricing header
+   - Literal headline: "Pricing"
+   - Short value sentence tied to operations outcomes
+   - Monthly/annual toggle
+
+2. Plan cards
+   - Starter, Pro, Enterprise
+   - Pro highlighted
+   - Exact CTA per plan
+   - Objection killer under primary CTA
+
+3. Operational value strip
+   - Saved hours/month
+   - Faster reporting
+   - Forecast confidence
+
+4. Feature comparison
+   - Compact by default
+   - Grouped by buyer concern
+
+5. Enterprise proof
+   - Security/procurement cues
+   - Sales CTA
+
+6. FAQ
+   - Billing, cancellation, data, procurement
+```
+
+### Quality Gate
+
+Before shipping:
+
+- Styles influenced the visual language.
+- Screens influenced concrete pricing structure.
+- Flows influenced the post-click journey.
+- The page does not copy one reference directly.
+- The palette does not default to generic indigo/violet.
+- The first viewport makes the pricing decision clear.
+- Buyer objections are handled near the relevant action.
+- The page has one memorable detail tied to this product's value.

package/skills/ui/refero-design/references/icons.md

@@ -0,0 +1,166 @@
+# Icons & Glyphs Guide
+
+In product UI, treat icons as typography — functional, not decorative.
+
+---
+
+## Two Contexts
+
+| Context | Style | Rule |
+|---------|-------|------|
+| **Product UI** | Clean outline or solid, one consistent set | Predictable, scalable, themeable |
+| **Marketing** | Duotone, gradients, illustrative allowed | Never leaks into product |
+
+---
+
+## Icon Sizing
+
+**Canvas** = the bounding box icons are designed within. Most libraries use 24×24px as base, but this is convention, not law.
+
+**Display sizes** depend on context:
+- Small (16px): inline with body text, table cells, dense UI
+- Medium (20–24px): buttons, nav items, form inputs
+- Large (28–32px): feature cards, empty states, marketing
+
+**Stroke weight** varies by library and style:
+- Thinner (1.5px): lighter feel, works better at larger sizes
+- Standard (2px): common default in Lucide, Heroicons
+- Thicker (2.5px+): bolder presence, better at small sizes
+
+**Round vs square caps/joins:** Round feels friendlier, modern. Square feels more technical, precise. Match your product's tone.
+
+**Key principle:** Pick one library or define your own spec. Consistency matters more than specific values.
+
+---
+
+## Optical Corrections
+
+What separates "adequate" from "premium."
+
+**Centering:** Geometric center ≠ visual center.
+- Play triangles → shift right 0.5–1px
+- Chevrons/arrows → shift toward point
+- **Test:** Put icon in a circle. Looks centered? If not, adjust.
+
+**Weight:** Different shapes have different visual mass at same stroke.
+- Circles appear lighter than squares
+- Diagonals appear thinner than horizontals
+- **Aim for equal visual mass**, not equal measurements
+
+---
+
+## Style Consistency
+
+One language per product. No exceptions.
+
+| Style | Best For |
+|-------|----------|
+| **Outline** | Dense UIs, data-heavy products |
+| **Solid** | Consumer apps, clear actions |
+| **Variable glyphs** | Design systems (SF Symbols, Material Symbols) |
+
+**Don'ts:**
+- ❌ Outline in nav + solid in buttons + duotone in cards
+- ❌ Mixing libraries (Lucide + Heroicons = collage)
+- ❌ Custom icons that ignore the system's grid/stroke
+
+---
+
+## Icon + Text Pairing
+
+Starting point — adjust based on visual testing:
+
+| Text Size | Icon Size |
+|-----------|-----------|
+| 14–16px | 16px |
+| 16–18px | 18–20px |
+| Headings | 20–24px |
+
+**Alignment:** Icons need `align-items: center` + often 0.5–1px manual tweak.
+
+**Weight harmony:** Semibold text + thin icon = "from different systems." Match weights or use solid.
+
+---
+
+## Color
+
+**Default:** `currentColor` — inherits text color, syncs with themes automatically.
+
+**Semantic:** Red (error), green (success), amber (warning) — only for status, never decoration.
+
+**Contrast:** Meaningful icons need **3:1 ratio** (WCAG non-text). Applies to icon buttons, toggles, status indicators.
+
+---
+
+## Accessibility
+
+| Type | Requirement |
+|------|-------------|
+| Action icons | `aria-label` on button, or visible text nearby |
+| Decorative icons | `aria-hidden="true"` |
+| Icon buttons | Hit area: 44×44px on touch, 32×32px on desktop (visual can be smaller) |
+
+---
+
+## Pre-Ship Checklist
+
+- [ ] **50% scale:** Icons readable when zoomed out?
+- [ ] **Grayscale:** States clear without color?
+- [ ] **Dark theme:** Outline icons don't disappear?
+- [ ] **Table rows:** Icons don't overpower text?
+- [ ] **Contrast:** Icon buttons meet 3:1?
+- [ ] **Touch targets:** 44px+ hit area?
+- [ ] **Consistency:** Same style everywhere?
+
+---
+
+## Libraries
+
+### For Product UI (SVG-based)
+
+| Library | Style | When to Use |
+|---------|-------|-------------|
+| **Lucide** | Outline only | SaaS default. Clean, consistent, 24×24/2px stroke. |
+| **Heroicons** | Outline + Solid | Tailwind projects. Two variants per icon. |
+| **Phosphor** | 6 weights | Need weight flexibility without variable fonts. |
+
+### Variable Glyph Systems
+
+Best when icons must match text weight dynamically.
+
+**Material Symbols (Web)**
+
+```css
+/* Include from Google Fonts, then: */
+.icon {
+  font-family: 'Material Symbols Outlined';
+  font-variation-settings: 
+    'FILL' 0,      /* 0 = outline, 1 = solid */
+    'wght' 500,    /* match your text weight */
+    'opsz' 24;     /* optical size: 20, 24, 40, 48 */
+}
+```
+
+- `wght`: Sync with text (400, 500, 600)
+- `opsz`: Increase for smaller icons (better clarity)
+- `FILL`: Toggle outline/solid per icon
+
+**SF Symbols (Apple/Native)**
+
+- Automatically matches San Francisco font weight
+- Scale axis for emphasis (small/medium/large)
+- Use in SwiftUI/UIKit, not web
+
+### When to Use What
+
+| Scenario | Choice |
+|----------|--------|
+| Web SaaS, quick start | Lucide |
+| Tailwind project | Heroicons |
+| Need weight sync with text | Material Symbols |
+| Apple native app | SF Symbols |
+| Multiple weights, no variable fonts | Phosphor |
+
+---
+
+*Icons are typography. Consistent, optical, accessible. If it doesn't read instantly—simplify.*

package/skills/ui/refero-design/references/mcp-tools.md

@@ -0,0 +1,258 @@
+# Refero MCP Tools Reference
+
+MCP clients may namespace tool names, but the Refero tools are exposed with the
+`refero_` prefix. Use the exact tool names shown by the client.
+
+Refero has three research layers:
+
+1. Styles - visual direction and taste.
+2. Screens - concrete UI patterns and product-screen decisions.
+3. Flows - multi-step journey logic.
+
+## Styles
+
+### `refero_search_styles`
+
+Search curated design styles using semantic search.
+
+Use first for any task with visual direction, brand feel, typography, color, layout,
+spacing, elevation, components, imagery, art direction, design-system inspiration, or
+visual polish.
+
+What results contain:
+
+- style UUID
+- title
+- source URL
+- preview image URL
+- platform
+- rich natural-language description of the visual language
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `query` | string | Yes | Semantic query for aesthetic, domain, audience, category, or brand direction. |
+| `page` | number | No | Pagination. Use later pages to explore less obvious directions. |
+
+Good queries:
+
+```text
+editorial monochrome SaaS landing page
+warm trustworthy healthcare product marketing
+premium fintech website with restrained typography
+developer tool website with product screenshots
+luxury ecommerce editorial product page
+productivity SaaS with airy spacing
+Attio editorial SaaS typography
+Linear changelog dark developer tool
+```
+
+Search method:
+
+- Search 3-5 different visual angles.
+- Include one broad aesthetic query.
+- Include one domain/category query.
+- Include one known-brand or strong-product query when relevant.
+- Do not stop at the first good result.
+
+Current coverage:
+
+- Styles currently focus on web marketing/product pages: landing pages, pricing pages,
+  product marketing sites, editorial brand sites, and SaaS websites.
+- Styles do not currently cover in-app dashboards, auth screens, settings screens, or iOS
+  app screens as style systems.
+- Even for product UI, use styles to establish taste and visual language, then use
+  screens/flows for product-specific logic.
+
+### `refero_get_style`
+
+Retrieve full design style references for one or more style UUIDs.
+
+Use after `refero_search_styles` to turn promising style previews into actionable design
+material.
+
+What results may include:
+
+- visual thesis / north star
+- colors and usage roles
+- typography and type scale
+- layout guidance, section rhythm, and composition patterns
+- spacing, radius, shadows, elevation, surfaces
+- component treatments and sometimes component/code examples
+- imagery, graphics, illustration, or product screenshot treatment
+- do/don't rules
+- agent prompt guidance or implementation notes
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `style_id` | string | Yes* | Style UUID from `refero_search_styles`. *Exactly one of `style_id` or `style_ids` must be provided.* |
+| `style_ids` | string[] | Yes* | Array of style UUIDs. Full styles are large; recommended max batch is 3-4. *Exactly one of `style_id` or `style_ids` must be provided.* |
+| `response_format` | enum | No | `json` or `md`. Default: `md`. |
+
+How to use returned styles:
+
+- Treat each style as a reference ingredient, not a template.
+- Pick one primary foundation for mood and density.
+- Borrow 1-2 specific details from other styles.
+- Extract layout, component, spacing, and elevation rules, not only colors and fonts.
+- Preserve source token/component roles instead of repurposing them.
+- Preserve imagery/media roles. Use real/generated/stock assets when possible; use an
+  intentional placeholder with art direction when the needed asset is unavailable.
+- Translate everything to the user's product, audience, and constraints.
+
+## Screens
+
+### `refero_search_screens`
+
+Search real UI screens using semantic search.
+
+Use for concrete interface decisions: page structure, component choices, content
+hierarchy, copy, states, and product-specific patterns.
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `query` | string | Yes | Search by screen type, UI element, pattern, state, company, or on-screen text. |
+| `platform` | enum | Yes | `web` for web app/site patterns, `ios` for mobile app patterns. |
+| `page` | number | No | Pagination. Use later pages to explore beyond obvious results. |
+
+Good queries:
+
+```text
+pricing page annual monthly toggle
+feature comparison table
+dashboard empty state
+billing settings cancellation modal
+onboarding progress indicator
+2FA setup recovery codes
+data table filters
+destructive action confirmation
+```
+
+Search guidance:
+
+- Search by what is literally on the screen.
+- Prefer concrete UI terminology over broad aesthetic words.
+- If the main query is aesthetic ("premium", "minimalist", "editorial", "dark"), search
+  styles first.
+- Use `page` for search pagination. Do not pass `limit`, `image_size`, or
+  `include_similar` to search tools.
+
+### `refero_get_screen`
+
+Get full details for one or more screens by UUID.
+
+Use after `refero_search_screens` when a result looks relevant and you need deeper
+metadata, descriptions, app/site info, patterns, elements, fonts, or content structure.
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `screen_id` | string | Yes* | One screen UUID. Use exactly one of `screen_id` or `screen_ids`. |
+| `screen_ids` | string[] | Yes* | Multiple screen UUIDs. Use exactly one of `screen_id` or `screen_ids`. |
+
+Batching:
+
+- Retrieve a few strong screens at a time.
+- If a batch fails, retry with fewer IDs.
+
+### `refero_get_similar_screens`
+
+Get visually and functionally similar screens for a screen UUID.
+
+Use when one screen is especially relevant and you want comparable examples fast.
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `screen_id` | string | Yes | UUID from `refero_search_screens` or `refero_get_screen`. |
+| `limit` | number | No | Number of similar screens. Default is usually 10; max is usually 20. |
+
+### `refero_get_screen_image`
+
+Get raw screenshot image content by UUID.
+
+Use only when text metadata is not enough and you need to visually inspect the exact
+screenshot. This returns image content and can use more context than text tools.
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `screen_id` | string | Yes | UUID from `refero_search_screens` or `refero_get_screen`. |
+| `image_size` | enum | No | `thumbnail` or `full`. Default: `thumbnail`. |
+
+## Flows
+
+### `refero_search_flows`
+
+Search user flows: connected screens showing how a user completes a task.
+
+Use for journey logic: onboarding, checkout, signup, cancellation, upgrade, settings,
+account deletion, password reset, and other before/after sequences.
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `query` | string | Yes | Search by task, journey, company, industry, or key step. |
+| `platform` | enum | Yes | `web` for web app/site flows, `ios` for mobile app flows. |
+| `page` | number | No | Pagination. Use later pages to explore more examples. |
+
+Good queries:
+
+```text
+signup onboarding
+checkout with promo code
+subscription cancellation
+account deletion feedback
+password reset 2FA
+workspace billing upgrade
+```
+
+### `refero_get_flow`
+
+Get full details for one or more user flows.
+
+Use after `refero_search_flows` to understand step-by-step goals, actions, system
+responses, screens, user problem, and related search queries.
+
+Parameters:
+
+| Parameter | Type | Required | Notes |
+|-----------|------|----------|-------|
+| `flow_id` | number | Yes* | Numeric flow ID. Use exactly one of `flow_id` or `flow_ids`. |
+| `flow_ids` | number[] | Yes* | Multiple numeric flow IDs. Use exactly one of `flow_id` or `flow_ids`. |
+
+## Response Formats
+
+Some clients expose a `response_format` parameter on Refero tools. Use it only when the
+tool schema shown by your client includes it:
+
+- `md` / markdown for human-readable research notes.
+- `json` for structured comparison or when extracting fields programmatically.
+
+## Common Mistakes
+
+- Do not use old `_tool` suffixed names.
+- Do not call `get_design_guidance`; use styles/screens/flows research instead.
+- Do not pass `image_size` to `refero_get_screen`; use `refero_get_screen_image` for raw images.
+- Do not pass `include_similar` to `refero_get_screen`; use `refero_get_similar_screens`.
+- Do not use screens as the main source for visual taste when styles are available.
+- Do not assume styles include dashboards, auth screens, or iOS app screens as style systems.
+- Do not copy a single style directly.
+
+## If Results Are Weak
+
+- Broaden the query.
+- Remove extra adjectives or constraints.
+- Search adjacent categories.
+- Try a known-product or best-brand query.
+- Inspect later pages.
+- For sparse flows, search related screens and reconstruct the journey manually.