@su-record/vibe 2.6.1 → 2.6.3

package/agents/ui-previewer.md

@@ -1,40 +1,146 @@
 ---
-description: Preview UI with ASCII art
-argument-hint: "UI description"
+description: Preview UI with Gemini image or ASCII art fallback
+argument-hint: "UI description or design folder path"
 ---
 
 # /vibe.ui
 
-Preview UI with ASCII art.
+Preview UI from description or design guide folder.
+
+- **Gemini enabled**: Generate actual UI image
+- **Gemini disabled**: ASCII art fallback
 
 ## Usage
 
 ```
-/vibe.ui "login page"
-/vibe.ui "dashboard" --layout grid
+/vibe.ui "login page"                    # Text description
+/vibe.ui "dashboard" --layout grid       # With layout option
+/vibe.ui ./design/                       # Design guide folder
+/vibe.ui ./mockups/login.html            # Single HTML file
 ```
 
 ## Process
 
-### 1. Analyze UI Description
+### 0. Detect Input Type
+
+First, determine if input is:
+
+- **Text description**: Generate UI from description
+- **Folder path**: Read design files and generate UI
+- **File path**: Read single file and generate UI
+
+**Detection logic:**
+
+```
+if (input starts with "./" or "/" or contains "/" or "\") → path
+else → text description
+```
+
+### 1. If Folder/File Path: Read Design Files
+
+**Supported file formats:**
+
+| Format | Purpose | How to read |
+| ------ | ------- | ----------- |
+| `*.html` | HTML mockups/prototypes | Read and parse structure |
+| `*.md` | Design guide documents | Read content |
+| `*.json` | Design tokens, theme config | Parse JSON |
+| `*.css` / `*.scss` | Style variables, colors | Extract variables |
+| `*.png` / `*.jpg` / `*.webp` | UI screenshots, mockups | **Use Read tool** (multimodal) |
+| `*.svg` | Icons, vector graphics | Read as XML |
+| `*.figma.json` | Figma export | Parse components |
+
+**Reading images:**
+
+Claude can read images using the Read tool. When encountering image files:
+
+1. Use Read tool to view the image
+2. Analyze UI structure, colors, layout from the image
+3. Extract component hierarchy
+
+**Folder scanning priority:**
+
+1. `*.html` files first (main structure)
+2. `*.png` / `*.jpg` images (visual reference)
+3. `*.json` (design tokens)
+4. `*.css` / `*.scss` (styles)
+5. `*.md` (documentation)
+
+**Example folder structure:**
+
+```
+design/
+├── mockup.html          # Main HTML mockup
+├── screenshot.png       # UI screenshot
+├── tokens.json          # Design tokens
+├── variables.css        # CSS variables
+└── style-guide.md       # Documentation
+```
+
+### 2. Analyze UI (from description or files)
+
+Analyze the UI structure:
 
-Analyze user's requested UI description:
 - Page/component name
 - Required UI elements (buttons, inputs, cards, etc.)
 - Layout structure (header-footer, sidebar, grid, etc.)
+- **Colors and typography** (from design tokens/CSS)
+- **Component hierarchy** (from HTML/images)
+
+### 3. Check Gemini Status and Generate
+
+**Check Gemini authentication:**
+
+```bash
+vibe gemini status
+```
+
+Or check config file: `~/.config/vibe/gemini.json`
+
+#### If Gemini Enabled: Generate UI Image
+
+Use Gemini Image API to generate actual UI mockup:
+
+**Prompt template for Gemini:**
+
+```
+Generate a modern UI mockup image for:
+
+[UI Description from step 2]
+
+Style requirements:
+- Clean, modern design
+- [Colors from design tokens if available]
+- [Typography from style guide if available]
+- Mobile-first responsive layout
+- Include all specified components
+
+Output: High-quality UI mockup image (1280x720 or similar)
+```
+
+**Execution:**
+
+```bash
+node hooks/scripts/generate-brand-assets.js \
+  --type "ui-mockup" \
+  --description "[analyzed UI description]" \
+  --colors "[extracted colors]" \
+  --output "./ui-preview.png"
+```
 
-### 2. Generate ASCII Art
+**Output location:** `./ui-preview-{timestamp}.png`
+
+#### If Gemini Disabled: ASCII Art Fallback
 
 Generate ASCII art based on the UI description:
 
 **Input format:**
+
 - Page name
 - Layout type (centered, sidebar, grid, header-footer)
 - Components list (type, label, position)
 
-### 3. Output ASCII Art
-
-Output generated ASCII art:
+**Example ASCII output:**
 
 ```
 ┌─────────────────────────────────────────┐
@@ -61,12 +167,14 @@ Output generated ASCII art:
 Suggest list of components needed for UI:
 
 **Required Components:**
+
 - `Header.tsx` - Header ("Welcome")
 - `LoginForm.tsx` - Form container
 - `Input.tsx` - Reusable input field
 - `Button.tsx` - Login button
 
 **Expected File Structure:**
+
 ```
 src/
 ├── components/
@@ -80,12 +188,41 @@ src/
     └── LoginPage.tsx
 ```
 
-## Example
+## Example (with Gemini)
+
+```
+User: /vibe.ui ./design/dashboard/
+
+Claude: Reading design folder...
+  - Found: mockup.png, tokens.json, style-guide.md
+
+Analyzing design files...
+  - Layout: Sidebar + Main content
+  - Colors: Primary #2F6BFF, Background #F5F5F5
+  - Components: Header, Sidebar, 3 StatCards, Footer
+
+Generating UI mockup with Gemini...
+
+✅ UI Preview generated: ./ui-preview-1706234567.png
+
+[Image displayed]
+
+**Component Breakdown:**
+1. Header (logo, user menu)
+2. Sidebar (navigation)
+3. StatsCard (reusable card)
+4. Footer (copyright, links)
+5. DashboardLayout (overall layout)
+
+Next step: /vibe.spec "dashboard page"
+```
+
+## Example (ASCII Fallback)
 
 ```
 User: /vibe.ui "Dashboard page - header, sidebar, main content (3 cards), footer"
 
-Claude: Generating dashboard UI preview...
+Claude: Gemini not configured. Using ASCII preview...
 
 ┌────────────────────────────────────────────────────────┐
 │  [Logo]  Dashboard                    [User] [Logout]  │
@@ -114,15 +251,17 @@ Claude: Generating dashboard UI preview...
 - Main: grid (3 columns)
 - Responsive: Changes to 1 column on mobile
 
-Next step:
-  vibe spec "dashboard page"
+💡 Tip: Run `vibe gemini auth` for actual UI image generation
+
+Next step: /vibe.spec "dashboard page"
 ```
 
 ## Notes
 
 - For complex UI, request in multiple parts
 - Layout options: `sidebar`, `header-footer`, `grid`, `centered`, `split`
-- ASCII art is for quick visualization before actual implementation
+- Gemini generates high-quality mockups; ASCII is for quick visualization
+- Design folder input extracts colors, typography, and component structure automatically
 
 ---
 

package/agents/ui-syncer.md

@@ -0,0 +1,259 @@
+---
+description: Sync UI code with design files
+argument-hint: "design folder path"
+---
+
+# /vibe.ui-sync
+
+Analyze design files and update existing UI code to match.
+
+## Usage
+
+```
+/vibe.utils --ui-sync ./design/ui/
+/vibe.utils --ui-sync ./mockups/
+/vibe.utils --ui-sync ./design/homepage.html
+```
+
+## Process
+
+### 1. Read ALL Design Files
+
+**MANDATORY: Read every file in the design folder.**
+
+Scan folder and read ALL supported files:
+
+| Format | What to Extract |
+| ------ | --------------- |
+| `*.html` | Structure, components, layout, classes |
+| `*.png` / `*.jpg` / `*.webp` | Visual layout, colors, spacing, typography |
+| `*.json` | Design tokens, theme config, component props |
+| `*.css` / `*.scss` | Variables, colors, spacing, typography |
+| `*.md` | Design guidelines, component specs |
+| `*.svg` | Icons, vector assets |
+
+**Reading order:**
+
+1. `*.md` files first (design specs/guidelines)
+2. `*.html` files (structure reference)
+3. `*.png` / `*.jpg` images (visual reference - use Read tool)
+4. `*.json` (design tokens)
+5. `*.css` / `*.scss` (styles)
+
+**CRITICAL:** Do NOT skip any file. Read images with the Read tool.
+
+### 2. Analyze Design Intent
+
+From all design files, extract:
+
+**Layout:**
+- Page structure (header, sidebar, main, footer)
+- Grid system (columns, gaps)
+- Responsive breakpoints
+
+**Components:**
+- Component hierarchy
+- Component names and types
+- Props and variants
+
+**Styling:**
+- Color palette (primary, secondary, accent, background, text)
+- Typography (font family, sizes, weights)
+- Spacing system (padding, margin, gaps)
+- Border radius, shadows
+- Dark/light theme support
+
+**Interactions:**
+- Button states (hover, active, disabled)
+- Form validation styles
+- Animations/transitions
+
+### 3. Find Existing UI Code
+
+Search for existing UI implementation:
+
+```
+src/components/
+src/pages/
+src/views/
+src/ui/
+app/components/
+app/(routes)/
+```
+
+Detect framework:
+- React: `*.tsx`, `*.jsx`
+- Vue: `*.vue`
+- Svelte: `*.svelte`
+- Angular: `*.component.ts`
+
+### 4. Compare Design vs Code
+
+Create a diff report:
+
+| Aspect | Design | Current Code | Action |
+| ------ | ------ | ------------ | ------ |
+| Colors | #2F6BFF | #3B82F6 | Update |
+| Font | Inter | system-ui | Update |
+| Border radius | 12px | 8px | Update |
+| Component X | Exists | Missing | Create |
+
+### 5. Generate Update Plan
+
+List all changes needed:
+
+**Style Updates:**
+```css
+/* Before */
+--primary: #3B82F6;
+--radius: 8px;
+
+/* After */
+--primary: #2F6BFF;
+--radius: 12px;
+```
+
+**Component Updates:**
+```tsx
+// Before: Missing hover state
+<Button>Click</Button>
+
+// After: Add hover state from design
+<Button className="hover:bg-primary-600">Click</Button>
+```
+
+**New Components:**
+- List components that exist in design but not in code
+
+### 6. Execute Updates
+
+**Ask user before making changes:**
+
+```
+Found 12 differences between design and code:
+- 3 color updates
+- 2 spacing changes
+- 1 new component
+- 6 style adjustments
+
+Proceed with updates? [Y/n]
+```
+
+**Apply changes:**
+
+1. Update CSS/SCSS variables
+2. Update Tailwind config (if applicable)
+3. Update component styles
+4. Create new components (if needed)
+5. Update imports
+
+### 7. Verify Changes
+
+After updates:
+
+1. Run build to check for errors
+2. Show before/after comparison
+3. List all files modified
+
+## Output Format
+
+```
+📂 Design Analysis: ./design/ui/
+
+Files Read:
+  ✓ homepage.html (structure)
+  ✓ homepage.png (visual)
+  ✓ tokens.json (design tokens)
+  ✓ styles.css (variables)
+
+Design Specs Extracted:
+  Colors: #2F6BFF (primary), #1E293B (text), #F8FAFC (bg)
+  Typography: Inter, 14px base, 1.5 line-height
+  Spacing: 4px base unit
+  Border Radius: 12px (cards), 8px (buttons)
+
+Differences Found: 8
+
+| File | Change | Status |
+|------|--------|--------|
+| tailwind.config.js | Update primary color | ⏳ Pending |
+| src/components/Button.tsx | Add hover state | ⏳ Pending |
+| src/styles/globals.css | Update CSS variables | ⏳ Pending |
+
+Apply changes? [Y/n]
+
+✅ Updated 3 files
+  - tailwind.config.js
+  - src/components/Button.tsx
+  - src/styles/globals.css
+
+Next: Run `npm run build` to verify
+```
+
+## Example
+
+```
+User: /vibe.utils --ui-sync ./design/dashboard/
+
+Claude: Reading design folder...
+
+📂 Files found:
+  - dashboard.html
+  - dashboard-dark.png
+  - dashboard-light.png
+  - tokens.json
+  - components.md
+
+Reading dashboard.html...
+[Extracts: header, sidebar, 3-column grid, card components]
+
+Reading dashboard-dark.png...
+[Analyzes: dark theme colors, spacing, typography]
+
+Reading tokens.json...
+[Extracts: color palette, spacing scale, typography scale]
+
+📊 Design Analysis Complete:
+
+Layout: Header + Sidebar + 3-column main
+Theme: Dark (#0F172A bg, #F8FAFC text)
+Components: Header, Sidebar, StatCard, DataTable
+
+🔍 Comparing with existing code...
+
+Found: src/pages/Dashboard.tsx
+Found: src/components/StatCard.tsx
+Missing: src/components/DataTable.tsx
+
+Differences:
+1. StatCard border-radius: design=16px, code=8px
+2. Sidebar width: design=240px, code=200px
+3. Header height: design=64px, code=56px
+4. Primary color: design=#6366F1, code=#3B82F6
+5. DataTable component: missing
+
+Apply 4 updates + create 1 component? [Y/n]
+
+User: Y
+
+✅ Changes applied:
+  - src/components/StatCard.tsx (border-radius)
+  - src/components/Sidebar.tsx (width)
+  - src/components/Header.tsx (height)
+  - tailwind.config.js (primary color)
+  - src/components/DataTable.tsx (created)
+
+Run `npm run dev` to preview changes.
+```
+
+## Notes
+
+- Always read ALL files including images
+- Ask for confirmation before making changes
+- Preserve existing functionality while updating styles
+- Create backup recommendation for large changes
+- Support both CSS-in-JS and traditional CSS
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/commands/vibe.utils.md

@@ -11,6 +11,7 @@ Collection of utility tools. Use with options.
 
 ```
 /vibe.utils --ui "description"       # UI ASCII preview
+/vibe.utils --ui-sync ./design/      # Sync UI code with design files
 /vibe.utils --diagram                # Architecture diagram
 /vibe.utils --diagram --er           # ERD diagram
 /vibe.utils --diagram --flow         # Flowchart
@@ -29,15 +30,78 @@ Collection of utility tools. Use with options.
 
 ## --ui (UI Preview)
 
-Read and follow `agents/ui-previewer.md` for ASCII UI preview generation.
+Read and follow `agents/ui-previewer.md` for UI preview generation.
 
-Generate ASCII-based UI preview from description.
+Generate UI preview from description or design folder.
+
+- **Gemini enabled**: Actual UI mockup image
+- **Gemini disabled**: ASCII art fallback
+
+**Input types:**
+
+| Input | Example |
+| ----- | ------- |
+| Text description | `"Login form with email, password"` |
+| Design folder | `./design/` |
+| Single file | `./mockups/login.html` |
+
+**Supported file formats in folder:**
+
+- `*.html` - HTML mockups
+- `*.png` / `*.jpg` / `*.webp` - UI screenshots (Claude reads images)
+- `*.json` - Design tokens
+- `*.css` / `*.scss` - Style variables
+- `*.md` - Style guides
+- `*.svg` - Vector graphics
 
 **Example:**
+
 ```
 /vibe.utils --ui "Login form - email, password input + login button"
+/vibe.utils --ui ./design/dashboard/
+/vibe.utils --ui ./mockups/homepage.png
+```
+
+---
+
+## --ui-sync (Design to Code Sync)
+
+Read and follow `agents/ui-syncer.md` for design-to-code synchronization.
+
+Analyze design files (HTML, images, CSS, tokens) and update existing UI code to match.
+
+**What it does:**
+
+1. Read ALL design files (including images)
+2. Extract design specs (colors, typography, spacing, components)
+3. Compare with existing code
+4. Generate update plan
+5. Apply changes (with confirmation)
+
+**Supported file formats:**
+
+- `*.html` - Structure, layout, classes
+- `*.png` / `*.jpg` / `*.webp` - Visual reference (Claude reads images)
+- `*.json` - Design tokens, theme config
+- `*.css` / `*.scss` - Variables, colors, spacing
+- `*.md` - Design guidelines
+- `*.svg` - Icons, vectors
+
+**Example:**
+
+```
+/vibe.utils --ui-sync ./design/ui/
+/vibe.utils --ui-sync ./mockups/dashboard/
+/vibe.utils --ui-sync ./design/homepage.html
 ```
 
+**Output:**
+
+- Diff report (design vs code)
+- List of changes to apply
+- Confirmation prompt
+- Files modified
+
 ---
 
 ## --diagram (Diagram Generation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "Vibe - Claude Code exclusive SPEC-driven AI coding framework with 35+ integrated tools",
   "type": "module",
   "main": "dist/cli/index.js",