visual-concept

name	visual-concept
description	Collaborative UI concept mode — agent + human co-craft HTML artifacts with live preview, clean structure, and inline documentation. Use for wireframes, UI mockups, flow diagrams, and design exploration. This is "plan mode but in HTML": propose a concept, review the rendered preview, request changes, iterate until approved. The HTML artifact becomes shared documentation for both human and AI readers.
tags	["design","ui","concept","solo"]

Visual Concept — Collaborative UI Concept Mode

Overview

This skill enables a structured collaboration loop where agent and human co-create HTML UI concepts with live preview. Each concept is a self-contained HTML file (Tailwind CDN, no build step) with:

• All 4 states — loading, empty, error, populated — toggleable in-browser
• Inline comments explaining design intent for both human and AI readers
• Companion README.md — printable, markdownable, shareable as docs
• Live auto-refresh — edit HTML → browser updates instantly

When to use

Scenario	Why
Exploring a new UI concept	Before writing production code
Communicating a design idea	When words alone aren't enough
Reviewing interaction flow	To check all states and transitions
Documenting a UI decision	The HTML + README become the artifact
Comparing alternatives	Create two concepts side by side

Quick start

Launch a new concept via the solo command:

/solo:concept "a bot overview dashboard with metric tiles and recent activity"

The agent will:

1. Create .concepts/<slug>/ directory with template.html + README.md
2. Fill the template with your concept's HTML
3. Start the live server using .claude/skills/visual-concept/scripts/live-server.py
4. Report the URL
5. Enter the collaboration loop

Workflow

╔══════════════════════════════════════════════════════════════╗
║  LOOP: Propose → Review → Revise → Approve                  ║
║                                                             ║
║  1. HUMAN: /solo:concept "describe concept"                 ║
║  2. AGENT: Creates .concepts/<slug>/ with template.html +   ║
║            README.md, starts live server, reports URL        ║
║  3. HUMAN: Views preview, requests change                    ║
║  4. AGENT: Edits HTML, adds comments explaining intent       ║
║  5. Browser auto-refreshes → HUMAN reviews again             ║
║  6. ... repeat until concept is final                        ║
║  7. HUMAN: "approve" → concept is ready for PR/docs          ║
╚══════════════════════════════════════════════════════════════╝

Template reference

The base template at templates/base.html includes:

Header comment block

CONCEPT: [Name]
TARGET: [Screen/Component]
STATUS: Draft → Review → Final
DESIGNER: Human + AI

Tailwind CDN

Served from cdn.tailwindcss.com — no npm, no build. Add custom styles in the <style> block only when Tailwind utilities cannot express them.

State toggles (.no-print)

Floating buttons at bottom-right to switch between loading/empty/error/ populated states. Hidden when printing.

4-state component pattern

Each component has data-state on its container and data-state-content on each state's div. CSS hides/shows the matching state:

<section id="demo-card" data-state="populated">
  <div data-state-content="loading">...</div>
  <div data-state-content="empty">...</div>
  <div data-state-content="error">...</div>
  <div data-state-content="populated">...</div>
</section>

Call setState('demo-card', 'loading') from the browser console, or click the state toggle buttons.

Print styles

@media print hides .no-print elements and sets clean black-on-white text. The page is ready for PDF export or physical printing.

README.md companion

Every concept comes with a README.md file documenting:

• States covered (with checkbox checklist)
• Design decisions (layout, colors, interactions)
• Review notes (iteration history)
• File manifest

This file can be:

• Printed — clean markdown-to-PDF via any markdown renderer
• Shared — paste into PR descriptions, tickets, or docs
• Archived — keep as a design decision record

Live server

python3 .claude/skills/visual-concept/scripts/live-server.py --port 0 --dir .concepts/<slug>/

• Auto-assigns a free port (or specify --port 8080)
• Injects live-reload script into HTML responses
• With watchdog installed: instant reload on file changes
• Without watchdog: polls every 2 seconds
• Press Ctrl+C to stop

Design principles

See references/design-principles.md for the full doctrine:

1. Every surface defines all 4 states — loading, empty, error, populated
2. HTML is a communication artifact — commented for human + AI
3. Self-contained — Tailwind CDN, no build step
4. Printable + markdownable — @media print + README.md companion
5. Progressive disclosure — start with populated, add other states

Anti-patterns

• ❌ No raw hex colors without token comments
• ❌ No unfilled placeholders [...] in a "final" concept
• ❌ No framework imports — pure HTML only
• ❌ No Lorem Ipsum — use realistic copy
• ❌ No concept without at least populated + empty states

Attribution

This skill was created for the MeKnow platform. The template structure and collaboration workflow are original. The state-coverage and anti-ai-slop doctrines are adapted from design-taste-meknow/references/.

See design-taste-meknow/ATTRIBUTION.md for upstream lineage of the shared design principles (MIT via Leonxlnx/taste-skill, Apache-2.0 via nexu-io/open-design/craft/).