vibe-to-ui

A local design companion for vibe coding developers. It first classifies the target page archetype and density, then uses the user's product background to derive three plausible visual and spatial directions from references before formalizing any one of them into a design system. It extracts "style DNA" including motion systems, Consumer app UIUX needs, visual asset direction, mood boards, and previews, and turns vague aesthetic feelings into product-aware design decisions that actually fit the product surface. Inspiration may be a website URL, screenshot, images, music, or fuzzy intent — the agent adapts to what the user provides (see references/INSPIRATION-SOURCES.md). Cases can be saved into a global Inspiration Library under ~/.vibe-to-ui/inspirations/<product>/pages/<page>/ (full-scroll analysis + motion + annotated preview.html, with product-level synthesis) without putting raw cases into a profile. It can also persist a reusable Design Context profile under ~/.vibe-to-ui/profiles/<profile>/ (brand master, tokens, decisions, assets) and adapt it on demand into open-ended medium targets — examples include web, social-cover, and hyperframes, and users may define their own (e.g. linkedin, print-brochure) — without coupling user data to skill install/update. All exploration happens through standalone previews; the agent only touches the user's project when the user confirms a direction and asks to apply it.

Tip: Git-based Design Context remote sync (context remote / context sync) shares profiles/ and inspirations/ under ~/.vibe-to-ui via your own private repo. For hosted multi-project management beyond Git, see MonkeyUI SaaS.

When to use this skill

• User provides a website URL, screenshot, or design mockup and wants to extract its design system
• User provides a website URL or screenshot plus product context and wants the agent to extend it into 3 visual directions rather than copy it literally
• User wants the agent to first identify whether the target is a landing page, brand page, dashboard, B-end dense operations page, table-detail management page, docs page, onboarding flow, Consumer app / C-end app surface, or another page archetype
• User has a vague aesthetic feeling and wants to explore design directions with website URLs, inspiration images, or music recordings
• User shares a music recording or audio clip (a melody, song snippet, or recorded humming) to express the mood they want their UI to feel
• User describes a song, genre, or musical feeling they associate with their desired aesthetic
• User wants a page to feel more relaxed, editorial, cinematic, calm, spacious, premium, playful, or unlike a generic SaaS landing page
• User shares non-UI inspiration such as photography, landscapes, architecture, interiors, magazines, posters, packaging, fashion, album covers, film stills, illustrations, music, or video references and wants those signals translated into layout decisions
• User wants to define a motion system that matches the page's actual use case — including by sharing a live site URL for the agent to observe
• User describes a product personality or feeling (for example "reliable", "innovative", "playful") and wants motion guidance that matches
• User wants to create a mood board that stays appropriate for the target page type instead of drifting into the wrong archetype
• User has collected multiple reference images or site URLs and wants to see them synthesized into a cohesive visual story
• User wants a shareable design artifact that communicates aesthetic intent to collaborators or stakeholders
• User wants distinctive icons, illustrated feature icons, 3D object icons, social visuals, or generated brand assets that fit the product and design direction
• User has confirmed a design direction (from concept previews, mood boards, or design system previews) and wants to apply it to their project
• User wants to save brand visual language from a website URL or screenshot into a local Design Context profile (brand / product / client), separate from any one project repo
• User runs or asks for vibe-to-ui context --profile <profile> --target <medium> to load or generate medium-specific rules for any medium (examples: web, social-cover, hyperframes, or user-defined like linkedin, print-brochure) and hand them to the matching agent
• User wants a cross-project Inspiration Library — collect product pages (URLs/screenshots) under ~/.vibe-to-ui/inspirations/<product>/, get full-scroll aesthetic + motion analysis, product-level visual positioning, optionally link the product into a profile, and only merge the product design-seed.md into project DESIGN.md after confirmation

Reference Priority Rules

Before choosing a workflow, classify the user's inputs:

• Atmosphere / vibe reference: photography, landscapes, architecture, interiors, magazines, posters, packaging, fashion, album covers, film stills, illustrations, music, video, abstract feelings
• Concrete UI reference: website URLs, screenshots of products/webpages/apps, local projects, existing codebases

When both are present, always use this priority:

1. Concrete UI / project fidelity
2. Page type fidelity (goal, density, interaction model, module mix)
3. Visual material fidelity (image strategy, typography, density treatment, glass treatment, motion weight)
4. Atmosphere adjustment

Inspiration source intake

Adapt to whatever the user provides — website URL, screenshot, mood images, music, local project, description, or a mix. None of these is the default preferred channel. Follow references/INSPIRATION-SOURCES.md:

• If they share a URL → visit / fetch, read frontend cues, captures (Inspiration Library: full-scroll; other capabilities: selective), optional motion observation
• If they share a screenshot or image → analyze it directly; do not ask for a URL first
• If they share music / atmosphere / description → vibe path; do not insist on a live site
• If sources mix → use each for its role and state how they were weighted

This intake applies across Capabilities 1–4, Motion System, Mood Board, and Design Context whenever those source kinds appear — as equal options, not a URL-first policy.

Mandatory Stage 0: Page Type Identification

Before any design-system extraction, spatial-vibe exploration, mood-board generation, or project application, classify the target page type.

Always produce:

1. Primary page type
2. Secondary modifier if needed
3. Density level: low / medium / high
4. Confidence: high / medium / low
5. Evidence: the signals that drove the classification
6. Design consequences: what this classification means for spacing, hierarchy, imagery, components, and motion

Use these signals to classify page type:

• Business goal: conversion, browsing, monitoring, data entry, content consumption, configuration, execution
• Information density: how much content competes on screen at once
• Primary interaction mode: scrolling, reading, filtering, comparing, editing, approving, drilling into records
• Dominant modules: hero, feature grid, table, chart, sidebar nav, detail pane, form, wizard, feed
• Decision speed: emotional persuasion, calm reading, fast scanning, repeated operations

Common page types:

1. Landing / marketing page: persuasive storytelling, strong hero, lower density, higher visual drama
2. Brand showcase / portfolio: presentation-led, immersive imagery, editorial rhythm
3. Content / docs / editorial page: reading clarity, typographic hierarchy, stable navigation
4. E-commerce / catalog page: browsing, filtering, comparison, product-card systems
5. B-end dashboard / overview: metrics, monitoring, summaries, moderate-to-high density
6. B-end workbench / dense operations page: repeated actions, filters, tables, status chips, compact spacing
7. Data management / table-detail page: record list + detail + batch actions, strict scanability
8. Form / onboarding / wizard: guided steps, form grouping, completion feedback
9. Consumer app surface: C-end product experience, usually mobile-first or app-like, task-oriented but emotionally richer than B-end systems; often card/feed, tab, onboarding, empty-state, and detail-flow based

If the page is mixed, pick one primary type and note the secondary pattern. Example: "Primary: B-end workbench; Secondary: dashboard summary."

Two operating modes

• Reference Fidelity Mode: Use when the user provides a concrete UI, screenshot, live page, or local project. Goal: first match the page type and structural feel, then make the output look recognizably close to the reference before applying mood adjustments. To preserve the reference's layout structure, follow the structure-extraction path in references/SPATIAL-VIBE.md.
• Vibe Translation Mode: Use when the user provides only atmosphere references or abstract feelings. Goal: infer the intended page archetype from product context, then translate the mood into a UI direction that fits that archetype.

Default to Reference Fidelity Mode whenever a concrete UI or project is provided.

Non-negotiable rules

• Do not jump into free reinterpretation before identifying the target page type, density level, interaction model, page structure, typography hierarchy, material treatment, and motion intensity.
• When the mood conflicts with the page type, the page type wins first. Tune the vibe inside the archetype instead of changing the archetype accidentally.
• Do not produce a cinematic landing page treatment for a dense B-end workbench unless the user explicitly wants a strategic repositioning.
• For landing / brand / showcase surfaces, larger imagery, looser spacing, and more expressive motion are acceptable.
• For B-end dashboard / dense operations / table-detail surfaces, prioritize scanability, state clarity, compact but consistent spacing, form and table legibility, and restrained motion.
• For Consumer app / C-end app surfaces, prioritize mobile-first hierarchy, navigation clarity, touch feedback, state completeness, empty/onboarding quality, and brand memorability without turning the app screen into a landing page. Use references/CONSUMER-APP-DESIGN.md whenever this is the primary page type.
• If the reference's strongest signal comes from photographic landscapes, use real scenic imagery as the primary visual layer by default. Do not replace it with CSS-generated scenes unless the user explicitly asks for illustration or abstraction.
• When both a concrete UI reference and vibe images are provided, treat the vibe images as secondary; they should tune the output, not replace the reference structure or page type.
• When the user provides a concrete UI reference plus product background, default to reference-led exploration: derive 3 visual directions that stay faithful to the reference's page type and structural DNA while adapting mood, material, density posture, and motion to the user's actual product context.
• Use direct design-system extraction first only when the user explicitly asks for restoration, token extraction, exact replication, or "analyze this design system." Otherwise, a concrete reference should become source material for 3 contextual visual directions before token formalization.
• If page type confidence is low, ask one short clarification question before formalizing the design system.
• Default to visual output, not text-only output: for every exploration, extraction, mood-board, or spatial-vibe workflow, generate at least one standalone HTML visual artifact by default. Do not wait for the user to explicitly ask for a preview, visual draft, mockup, or demo.
• Do not stop at Markdown analysis alone when the workflow is meant to shape visual direction. Text analysis supports the visual artifact; it does not replace it.
• Before generating the UI, briefly summarize:
  • the inferred page type and density
  • what must stay similar to the reference
  • what may be adjusted
  • whether the task is operating in Reference Fidelity Mode or Vibe Translation Mode

Persistent DESIGN.md context

When a project has DESIGN.md, read it before visual design work and use it as persistent product/design context. When the file is missing and the workflow establishes meaningful product or visual strategy, create it from assets/DESIGN.md or add the relevant sections. See references/CONTEXT-COLLABORATION.md for the collaboration protocol.

Update DESIGN.md passively as the conversation reveals:

• product definition, users, use cases, personality, and constraints
• page type, density, interaction model, and design consequences
• confirmed visual direction, mood keywords, typography posture, motion personality, and imagery strategy
• icon_system: locked UI icon library, custom SVG fallback, preset, grid, stroke rules, and user overrides
• illustrated_icon_system: enabled surfaces, preset, format, visual family rules, style reference, and surfaces to avoid
• visual asset manifest paths, review surface paths, selected combinations, placement notes, validation status, confirmed assets, rejected assets, and regeneration notes
• active Design Context profile id when one is in use (e.g. design_context_profile: vibe-to-ui in Iteration Context)

Do not ask the user to manage this bookkeeping. Mention it only when it affects a design decision or when summarizing applied changes.

Local Design Context profiles (~/.vibe-to-ui/)

When the user wants reusable brand memory across projects or media, use Capability 7 and references/DESIGN-CONTEXT.md.

• A profile is a brand, product, or client (e.g. vibe-to-ui, acme-brand) — not an output platform.
• Live data lives only under ~/.vibe-to-ui/profiles/<profile>/. Skill templates under assets/design-context/ are seeds to copy, never the live store.
• Skill install, update, or reinstall must never overwrite, delete, or reset ~/.vibe-to-ui/.
• Prefer the Node CLI (bin/vibe-to-ui.js) for --list / --init / --target lifecycle, merge assembly, and optional Git remote sync (remote connect / remote status / sync).
• targets/<medium>.md files are created on first request for that medium (open-ended ids; web / social-cover / hyperframes are examples only), then reused and updated.
• Prefer an active profile's brand.md + tokens.json for brand fidelity; keep project DESIGN.md for product/page-local context.

Inspiration Library (~/.vibe-to-ui/inspirations/<product>/)

When the user wants to collect and understand external design references across projects, use Capability 8 and references/INSPIRATION-LIBRARY.md.

• Global library — not nested under a profile. Storage unit is a product with many pages (pages/<slug>/), not one folder per URL.
• Every URL page requires full-scroll captures + motion notes; product.md synthesizes multi-page visual DNA.
• Profiles may only store product references via inspiration-refs.json (reference-only by default).
• Do not copy raw inspiration cases into a profile. Default apply uses the product seed; write project DESIGN.md only after confirmation.
• Prefer the CLI: vibe-to-ui inspiration add|list|show|link|apply|rebuild-product.

Eight core capabilities

1. Design System Extraction (Design Style Restoration)

User provides a complete UI reference (website URL, screenshot, or design mockup) -> Extract the design system and generate a standalone preview page for the user to review before applying it to their project.

Trigger: User says things like "extract the style from this", "what's the design system here", "analyze this design", "analyze https://…", "what motion does this use", "replicate this closely", "restore this style", or clearly asks for exact tokenization rather than concept exploration.

Workflow:

1. Accept a website URL and/or a screenshot/image — whichever the user provides. If a URL is present, follow references/INSPIRATION-SOURCES.md for that link; if only an image is present, analyze it directly.
2. Run Stage 0: Page Type Identification
3. Analyze the reference systematically (live CSS/DOM + selective captures when from a URL), but interpret tokens through the page type lens:
   • layout rhythm and density
   • typography hierarchy and readability needs
   • color semantics, especially status and priority colors for B-end surfaces
   • component patterns that fit the classified archetype
4. Analyze the motion system with the page type in mind (Motion DNA only — do not load the Motion Engine Router yet):
   • landing pages can support more entrance choreography
   • dashboards prefer subtle transitions and focus-preserving movement
   • dense workbenches should avoid decorative motion that interrupts scanning
   • consumer apps need fast, tactile feedback, clear screen transitions, and complete reduced-motion fallbacks
   • extract tempo, easing, density, distance, personality, and one signature motion motif from the reference/vibe (see references/MOTION-SYSTEM.md)
5. Output a structured design system including:
   • page type summary
   • design constraints derived from the page archetype
   • visual tokens
   • motion tokens + signature motion motif
   • consumer app system fields from references/CONSUMER-APP-DESIGN.md when applicable
6. If the user wants a richer aesthetic guide (soul-level, not just tokens), also generate an Aesthetic Analysis document following references/AESTHETIC-ANALYSIS.md, but keep it subordinate to the page type constraints
7. Generate a standalone preview page as an HTML artifact showcasing the extracted design system applied to sample components. This is NOT applied to the project yet. When writing the preview's motion code, progressively load references/MOTION-ENGINE-ROUTER.md: compile Motion DNA → detect stack family (web / react / vue) → select one engine tier + stack binding → one primary recipe (mutate parameters from DNA/signature motif — do not ship recipe defaults unchanged) → dependency, mobile, and reduced-motion fallbacks. Only if the Router selects L5 MiniMax Video, load references/VIDEO-MOTION.md.
8. Ask the user to confirm or adjust both the page type classification and the extracted values
9. Once the user confirms, transition to Capability 5 (Apply Design to Project) to integrate the design system into the actual project

2. Design Exploration

User has feelings or vibes but no concrete design target -> Interactive conversation to discover and define aesthetics that still match the intended page archetype, generating standalone concept previews for collaborative exploration.

Trigger: User says things like "I want something that feels like...", "I have some inspiration images", "use https://… as inspiration", "I'm not sure what style I want", "explore other styles but keep these colors", shares mood or landscape photos, shares a music recording or song that captures the feeling they want, or provides a concrete UI reference (URL or screenshot) together with product context and wants the agent to extend it into multiple visual directions.