vibe-ship-it 1.4.1 → 1.5.0

package/README.md

@@ -1,9 +1,14 @@
 # Designer Vibe Coding Skill Pack
 
-A set of AI agents and skills that help designers vibe-code their ideas to life — without learning programming.
+[![npm version](https://img.shields.io/npm/v/vibe-ship-it)](https://www.npmjs.com/package/vibe-ship-it)
+[![npm downloads](https://img.shields.io/npm/dw/vibe-ship-it)](https://www.npmjs.com/package/vibe-ship-it)
+[![license](https://img.shields.io/npm/l/vibe-ship-it)](https://github.com/sso-ss/vibe-ship-it/blob/main/LICENSE)
+
+A set of AI agents and skills that help designers vibe-code their ideas to life, without learning programming.
 
 Works with **VS Code Copilot**, **Claude Code**, and **OpenAI Codex**.
 
+- Live site: https://vibe-ship-it.vercel.app
 - GitHub: https://github.com/sso-ss/vibe-ship-it
 - npm: https://www.npmjs.com/package/vibe-ship-it
 
@@ -153,6 +158,21 @@ skills/
 
 ## How DESIGN.md works
 
+The `generate-design-md` skill fetches a website's HTML and all linked CSS files, then extracts every visual token into a structured document that AI agents can read.
+
+**What it extracts:**
+- Full color system with HSL tokens and semantic roles (background, text, border, status)
+- Typography scale with font families, sizes, weights, line heights, and letter spacing
+- Spacing grid, container widths, and section gaps
+- Border radius scale, shadow system (including inset shadow-as-border techniques)
+- Motion tokens: durations, easing curves, backdrop blur values
+- Component patterns: buttons, cards, inputs, navigation
+- State treatments: hover, focus, active, disabled, loading, error
+- Dark mode mappings when present
+- Responsive breakpoints and what changes at each
+
+**Confidence tracking:** Each token is marked as `extracted` (found in CSS), `inferred` (deduced from patterns), or `known` (recognized from training data). If CSS files are blocked, a warning is added.
+
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │  DESIGNER INPUT                                                 │
@@ -168,9 +188,9 @@ skills/
 │                      ▼       ▼                                  │
 │               ┌──────────────────┐                              │
 │               │    DESIGN.md     │                              │
-│               │  (source of      │                              │
-│               │   truth for all  │                              │
-│               │   visual tokens) │                              │
+│               │  8-section       │                              │
+│               │  token system    │                              │
+│               │  with HSL vars   │                              │
 │               └────────┬─────────┘                              │
 │                        │                                        │
 │              ┌─────────┼─────────┐                              │
@@ -188,8 +208,22 @@ skills/
 └─────────────────────────────────────────────────────────────────┘
 ```
 
+**DESIGN.md sections:**
+1. Identity: visual personality in one line + signature techniques
+2. Color: full palette with semantic roles, neutral scale, dark mode
+3. Typography: fonts, scale, weight strategy
+4. Spacing & Layout: base unit, container, border radius
+5. Depth & Motion: elevation system, transitions, backdrop blur
+6. Components: buttons, cards, inputs, navigation, signature patterns
+7. States: hover, focus, active, disabled, loading, empty, error
+8. Rules: specific do's and don'ts with actual values
+
 Rule 0 enforces this: every agent silently checks for `DESIGN.md` before any work. If it exists, all colors, fonts, spacing, shadows, and radii come from that file. No inventing new values.
 
+## Try it live
+
+The [live site](https://vibe-ship-it.vercel.app) includes a design token extractor. Paste any URL and get a downloadable DESIGN.md with the full 8-section structure, Tailwind config, and CSS variables.
+
 ## Design principles
 
 - **Show results first, explain code second**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-ship-it",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "AI skill pack for designers who vibe-code. 4 agents, 14 skills, DESIGN.md generator. Just say what you want in plain English.",
   "bin": {
     "vibe-ship-it": "./bin/init.js"

package/template/CLAUDE.md

@@ -20,7 +20,7 @@ You help an excited designer build their idea. They are not a programmer. They t
 
 7. **Never enforce build order.** If they want to build page 3 before page 1, let them. If they want login after building 5 pages, accommodate without refactoring lectures.
 
-8. **No emoji or em dash in generated copy.** Never use emoji or em dash (—) in any user-facing text, UI copy, headings, or content you generate. Not in HTML, not in components, not in placeholder text. The only exception is if the designer explicitly asks for emoji.
+8. **No emoji or dashes in generated copy.** Never use emoji, em dash, or double dash (--) in any user-facing text, UI copy, headings, or content you generate. Use colons, commas, periods, or parentheses instead. The only exception is if the designer explicitly asks for emoji.
 
 ## Language Rules
 

package/template/_github/copilot-instructions.md

@@ -20,7 +20,7 @@ You help an excited designer build their idea. They are not a programmer. They t
 
 7. **Never enforce build order.** If they want to build page 3 before page 1, let them. If they want login after building 5 pages, accommodate without refactoring lectures.
 
-8. **No emoji or em dash in generated copy.** Never use emoji or em dash (—) in any user-facing text, UI copy, headings, or content you generate. Not in HTML, not in components, not in placeholder text. The only exception is if the designer explicitly asks for emoji.
+8. **No emoji or dashes in generated copy.** Never use emoji, em dash, or double dash (--) in any user-facing text, UI copy, headings, or content you generate. Use colons, commas, periods, or parentheses instead. The only exception is if the designer explicitly asks for emoji.
 
 ## Language Rules
 

package/template/skills/build-page/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build-page
-description: "Builds UI from descriptions, screenshots, or Figma designs. Triggers: 'build a page', 'create a page', 'make a page', 'build the UI', 'make it look like', 'design this page', 'add a page', 'new page', 'home page', 'landing page', 'about page', 'contact page', 'hero section', 'add a section', 'layout', 'header', 'footer', 'navigation', 'sidebar', 'form', 'card', 'modal', 'build this'."
+description: "Builds UI from descriptions, screenshots, or Figma designs. Triggers: 'build a page', 'create a page', 'make a page', 'build the UI', 'make it look like', 'design this page', 'add a page', 'home page', 'landing page', 'about page', 'contact page', 'hero section', 'add a section', 'layout', 'header', 'footer', 'navigation', 'sidebar', 'form', 'card', 'modal', 'build this'."
 ---
 
 # Build Page

package/template/skills/generate-design-md/SKILL.md

@@ -13,10 +13,14 @@ Takes a website URL and produces a complete DESIGN.md file -- a plain-text desig
 2. Fetch the page HTML and all linked CSS
 3. Extract every visual token: colors, fonts, spacing, shadows, radii, component patterns
 4. Analyze the visual atmosphere and design philosophy
-5. Write a DESIGN.md in our 8-section format (optimized for AI agents, not human essays)
-6. Drop it in the project root
+5. Detect the page structure (sections, grids, layout patterns)
+6. Generate three files:
+   - `DESIGN.md` -- the complete design system (8 sections)
+   - Tailwind config extension -- tokens mapped to utility classes
+   - CSS variables -- tokens as custom properties in globals.css
+7. Drop them in the project
 
-One command. No questions. The output is a markdown file, not code.
+One command. No questions. The designer just sees the result.
 
 ## When To Use
 
@@ -341,11 +345,100 @@ If CSS extraction is limited, use the HTML structure and inline styles to infer
 
 ## After Generation
 
-Place the file at the project root as `DESIGN.md`. Say something like:
-- "Your design reference is ready. Any page you build now will follow [site name]'s visual style."
-- "Captured [site name]'s design. Colors, type, spacing, components -- it's all in DESIGN.md."
+Place the file at the project root as `DESIGN.md`. Then generate two companion files automatically:
+
+### 1. Tailwind Config Extension
+
+Create or update `tailwind.config.ts` (or the equivalent) with the extracted tokens mapped to Tailwind's theme:
+
+```ts
+// Auto-generated from DESIGN.md
+theme: {
+  extend: {
+    colors: {
+      background: 'rgb(255, 255, 255)',
+      surface: 'rgb(245, 245, 245)',
+      'text-primary': 'rgb(20, 20, 20)',
+      'text-secondary': 'rgb(112, 112, 112)',
+      'text-tertiary': 'rgb(173, 173, 173)',
+      accent: '#635bff',
+      border: 'rgb(237, 237, 237)',
+      // ... all extracted color tokens
+    },
+    borderRadius: {
+      sm: '8px',
+      md: '12px',
+      lg: '24px',
+      xl: '28px',
+      full: '9999px',
+    },
+    boxShadow: {
+      ring: 'inset 0 0 0 1px rgba(64, 64, 64, 0.16)',
+      low: '0 1px 2px rgba(0, 0, 0, 0.04)',
+      // ... all extracted shadows
+    },
+    fontWeight: {
+      normal: '400',
+      medium: '500',
+      semibold: '600',
+    },
+  },
+}
+```
+
+This lets the agent write `bg-background`, `text-text-primary`, `rounded-md`, `shadow-ring` instead of hardcoding values everywhere. If a Tailwind config already exists, merge into it without overwriting existing values.
+
+### 2. CSS Variables
+
+Add to `globals.css` (or the project's main CSS file):
+
+```css
+:root {
+  --background: rgb(255, 255, 255);
+  --surface: rgb(245, 245, 245);
+  --text-primary: rgb(20, 20, 20);
+  --text-secondary: rgb(112, 112, 112);
+  --border: rgb(237, 237, 237);
+  --accent: #635bff;
+  --radius-sm: 8px;
+  --radius-md: 12px;
+  --radius-lg: 24px;
+  --shadow-ring: inset 0 0 0 1px rgba(64, 64, 64, 0.16);
+  /* ... all extracted tokens */
+}
+```
+
+If the file already has `:root` variables, merge without overwriting.
+
+### 3. Page Structure (if detectable)
+
+Analyze the reference site's HTML structure and add a `## Page Structure` section at the end of DESIGN.md:
+
+```markdown
+## Page Structure
+
+Detected layout pattern from [site]:
+
+1. **Nav:** Sticky header, logo left, links center, CTA right
+2. **Hero:** Full-width, large heading centered, subtitle below, 2 buttons
+3. **Metrics:** 4-column stat grid with large numbers
+4. **Features:** 3-column card grid, icon + title + description per card
+5. **Testimonials:** 2-column quote cards with avatar + company
+6. **CTA:** Centered heading + button, full-width section
+7. **Footer:** Logo, link columns, copyright
+
+Grid patterns:
+- Feature grids: 3 columns on desktop, 1 on mobile
+- Card gaps: 16-24px
+- Section padding: 80-96px vertical
+```
+
+Detect this from the DOM tree -- look at semantic elements (`<nav>`, `<header>`, `<section>`, `<footer>`), grid/flex containers, column counts, and heading hierarchy. This gives the build-page skill a blueprint when the designer says "build me a landing page like that."
+
+### After creating all files, say:
+- "Your design reference is ready. Tailwind config and CSS variables are set up. Any page you build now follows [site name]'s style."
 
-Do not explain every section. The designer doesn't need a walkthrough of what a DESIGN.md is.
+Do not explain every section. The designer doesn't need a walkthrough.
 
 ## What Not To Do
 

package/template/skills/noob-mode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: noob-mode
-description: "Plain-English translation layer. Explains technical things in simple language. Triggers: 'what does that mean', 'explain', 'I don't understand', 'what happened', 'what is', 'confused', 'explain everything', 'noob mode', 'beginner mode', 'speak simply'."
+description: "Plain-English translation layer. Explains technical things in simple language. Triggers: 'what does that mean', 'I don't understand', 'what happened', 'what is', 'confused', 'explain everything', 'noob mode', 'beginner mode', 'speak simply'."
 ---
 
 # Noob Mode

package/template/skills/quick-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quick-check
-description: "Fast 3-item quality check. Triggers: 'check it', 'is this ready', 'does it look ok', 'quick check', 'any issues', 'look for problems', 'is it broken', 'test it'."
+description: "Fast 4-item quality check. Triggers: 'check it', 'is this ready', 'does it look ok', 'quick check', 'any issues', 'look for problems', 'is it broken', 'test it'."
 ---
 
 # Quick Check

package/template/skills/what-am-i-building/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: what-am-i-building
-description: "Figures out what you're building and sets up the project. Triggers: 'I want to build', 'I want to make', 'new project', 'start something', 'I have an idea', 'help me build', 'create a', 'build me a', 'I need a website', 'I need an app', 'make me a'."
+description: "Figures out what you're building and sets up the project. Triggers: 'I want to build', 'I want to make', 'new project', 'start something', 'I have an idea', 'help me build', 'I need a website', 'I need an app'."
 ---
 
 # What Am I Building