conductor-figma 0.3.1 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conductor-figma",
-  "version": "0.3.1",
+  "version": "1.0.1",
   "description": "Design-intelligent MCP server for Figma. 61 tools across 10 categories. 8px grid, type scale ratios, auto-layout, component reuse, accessibility — real design intelligence, not shape proxying.",
   "author": "0xDragoon",
   "license": "MIT",

package/src/design/craftguide.js

@@ -0,0 +1,181 @@
+// ═══════════════════════════════════════════
+// CONDUCTOR — Design Craft Guide
+// ═══════════════════════════════════════════
+// Professional design rules. The AI reads this before designing anything.
+// This is what separates amateur output from production quality.
+
+export function getDesignCraftGuide() {
+  return `# CONDUCTOR Design Craft Guide
+
+You are a senior product designer working in Figma. Every frame, every text node, every color choice must follow these rules. No exceptions.
+
+## Layout Architecture
+
+### Frame Structure
+- ALWAYS use auto-layout. Never absolute positioning.
+- Direction: VERTICAL for page sections, HORIZONTAL for rows of items.
+- Every frame needs explicit padding and gap. Never 0 unless intentional.
+- Use primaryAxisSizingMode: "HUG" for content-driven frames, "FIXED" for containers with set widths.
+- Use counterAxisSizingMode: "FILL" for child frames that should stretch to parent width.
+
+### Spacing System (8px grid)
+- Base unit: 8px. All spacing values must be multiples of 8.
+- Micro spacing: 4px, 8px (within components, between label and input)
+- Small spacing: 12px, 16px (between related elements, card padding)
+- Medium spacing: 24px, 32px (between component groups, section padding)
+- Large spacing: 48px, 64px (between page sections)
+- Extra large: 80px, 96px, 120px (page-level vertical rhythm)
+- NEVER use: 5, 7, 10, 13, 15, 17, 22, 25, 30, 35, 50, 55, 65, 70, 75, 90, 100
+
+### Content Width
+- Max content width: 1200px for desktop, centered in wider frames
+- For a 1440px page, use 48-80px horizontal padding to create margins
+- Card grid max: 3-4 columns. Never 5+ columns for content cards.
+- Sidebar: 240-280px. Never wider than 320px.
+
+## Typography
+
+### Type Scale (use Inter font family)
+- Display: 56-72px, Bold or Extra Bold, line-height 1.1
+- H1: 40-48px, Bold, line-height 1.15
+- H2: 32-36px, Bold or Semi Bold, line-height 1.2
+- H3: 24-28px, Semi Bold, line-height 1.25
+- H4: 18-20px, Semi Bold, line-height 1.3
+- Body large: 18px, Regular, line-height 1.6
+- Body: 15-16px, Regular, line-height 1.6
+- Body small: 13-14px, Regular, line-height 1.5
+- Caption: 11-12px, Medium, line-height 1.4
+- Overline: 10-12px, Semi Bold or Bold, uppercase, letter-spacing 0.08em
+
+### Typography Rules
+- Maximum 2 font weights per section (e.g., Bold + Regular, Semi Bold + Regular)
+- Body text color should NEVER be pure white (#ffffff). Use #f0f0f8 or #e8e8f0 for dark themes.
+- Muted text: #a0a0b8 for dark themes, #666680 for light themes.
+- Heading to body size ratio should be at least 1.5x.
+- Line length: 45-75 characters for body text. Use max-width on text containers.
+
+## Color
+
+### Dark Theme Palette
+- Background levels: #09090f → #0c0c18 → #0f0f1c → #12122a → #16163a
+- Each level should be visibly distinct but not jarring.
+- Card backgrounds should be 1-2 levels lighter than the page background.
+- Text hierarchy: #f0f0f8 (primary) → #a0a0b8 (secondary) → #686880 (tertiary)
+- Dividers: #1a1a32 or #1e1e3a (subtle, never bright)
+- NEVER use pure black (#000000) as a background.
+- NEVER use pure white (#ffffff) as text on dark backgrounds.
+
+### Light Theme Palette
+- Background levels: #ffffff → #f9f9fb → #f3f3f7 → #ebebf0
+- Card backgrounds: #ffffff with subtle border (#e4e4ec)
+- Text hierarchy: #111118 (primary) → #55556a (secondary) → #88889a (tertiary)
+- Dividers: #e4e4ec
+
+### Brand Color Usage
+- Primary brand color: buttons, links, badges, icons, active states.
+- NEVER use brand color for large background areas.
+- Brand color for text only in overlines, links, and badges.
+- Hover states: darken brand color by 10%. Active: darken by 15%.
+
+## Components
+
+### Buttons
+- Height: 36px (small), 40px (default), 48px (large), 56px (hero)
+- Horizontal padding: 16px (small), 20px (default), 28px (large), 32px (hero)
+- Corner radius: 8px (default), 10-12px (large/hero)
+- Primary: brand color fill, white text, Semi Bold
+- Secondary: transparent fill, border or muted text, Medium weight
+- Ghost: transparent, text only, Medium weight
+- Always center text both axes in buttons
+
+### Cards
+- Padding: 24-32px (compact), 28-40px (standard)
+- Corner radius: 12-16px
+- Gap between elements inside: 12-20px
+- On dark themes: use a lighter background, no border
+- On light themes: white background + subtle border (#e4e4ec) + optional shadow
+- Cards in a row should all be the same height (use counterAxisAlignItems: "STRETCH" on parent)
+
+### Navigation
+- Height: 64-72px for top nav
+- Logo left, links center or right, CTA button far right
+- Use a spacer frame (FILL sizing) between logo and links to push them apart
+- Nav links: 14px Medium, 24-32px gap between items
+- Active state: brand color or bolder weight
+- Add a 1px divider below the nav
+
+### Metric/Stat Cards
+- Stack: label on top (12-13px, muted, Medium), value below (28-36px, Bold)
+- Optional: change indicator below value (12-13px, green for positive, red for negative)
+- Equal width cards in a horizontal row
+- 20-24px gap between metric cards
+
+### Tables
+- Header row: 40-48px height, uppercase 10-11px labels, muted color, Medium weight
+- Data rows: 48-56px height, 14-15px Regular text
+- Cell padding: 16-20px horizontal
+- Alternating row backgrounds or horizontal dividers (not both)
+- Status badges: small colored pills with 4-6px padding, rounded
+
+### Forms
+- Input height: 40-44px
+- Label: 13-14px, Medium weight, 4-8px gap below label
+- Input: 14-15px Regular, 12-16px horizontal padding
+- Corner radius: 8px
+- Border: 1px, muted color. Focus: brand color border
+- 20-24px gap between field groups
+
+## Section Patterns
+
+### Hero Section
+- Vertical padding: 80-120px
+- Content centered (both axes)
+- Overline badge → Heading (56-72px) → Subtitle (18-20px) → Button row → Social proof
+- Max heading width: ~600px
+- Subtitle max width: ~500px
+- 28-32px gap between heading and subtitle
+- 32-40px gap between subtitle and buttons
+
+### Feature Section
+- Heading + subtitle centered at top
+- 3 cards in a row (or 2 for detailed features)
+- Each card: icon/emoji → title → description → optional link
+- 48px gap between heading group and card row
+
+### Stats/Social Proof
+- Background color shift (one level different from surrounding sections)
+- 3-4 stats in a horizontal row, centered
+- Each stat centered: big number + label below
+
+### CTA Section
+- Often wrapped in a card or a background shift
+- Centered: heading → subtitle → button row
+- Generous padding: 64-96px vertical
+
+### Footer
+- Logo left, copyright right, spacer between
+- Or: multi-column with link groups
+- Divider line above
+- Muted text, smaller font sizes (13px)
+
+## Anti-Patterns (NEVER do these)
+- Never use absolute positioning. Always auto-layout.
+- Never use font sizes that aren't in the type scale.
+- Never use spacing values that aren't multiples of 4 or 8.
+- Never put more than 3-4 cards in a row.
+- Never use pure black or pure white on dark themes.
+- Never make buttons without sufficient padding (minimum 16px horizontal).
+- Never stack more than 4-5 levels of nesting without good reason.
+- Never use inconsistent corner radii on the same page.
+- Never use more than 2-3 distinct background colors per page.
+- Never center-align body paragraphs (center headings only).
+- Never use text smaller than 11px.
+- Never create frames without naming them descriptively.
+
+## Naming Convention
+- Pages: "Landing Page", "Pricing Page", "Dashboard"
+- Sections: "Hero Section", "Features Section", "CTA Section"
+- Components: "Nav CTA", "Feature Card", "Stat Card", "Price Tier"
+- Layout: "Card Row", "Button Row", "Nav Links"
+- Never use "Frame 1", "Rectangle 2", or auto-generated names.`;
+}

package/src/index.js

@@ -30,3 +30,4 @@ export {
 } from './design/intelligence.js';
 
 export { exportCSS, exportTailwind, exportSCSS, exportJSON, exportW3CTokens } from './design/exporter.js';
+export { getDesignCraftGuide } from './design/craftguide.js';

package/src/relay.js

@@ -15,15 +15,17 @@ import { createServer } from 'node:http';
 const FIGMA_COMMANDS = new Set([
   // Create
   'create_frame', 'create_text', 'create_rect', 'create_section', 'create_component',
+  'create_ellipse', 'create_svg_node',
   // Layout
   'set_auto_layout', 'set_constraints', 'apply_grid', 'align_nodes',
   // Style
   'set_fills', 'set_strokes', 'set_effects', 'set_corner_radius', 'set_opacity',
   // Typography
-  'set_text_props', 'load_font',
+  'set_text_props', 'load_font', 'style_text_range',
   // Read
   'get_selection', 'get_page_info', 'get_styles', 'get_components',
   'read_node', 'read_tree', 'read_spacing', 'read_colors', 'read_typography',
+  'find_nodes',
   // Edit
   'rename_node', 'move_node', 'resize_node', 'delete_node',
   'clone_node', 'group_nodes', 'ungroup_node', 'reorder_node',

package/src/tools/handlers.js

@@ -6,6 +6,7 @@
 
 import * as design from '../design/intelligence.js';
 import * as exporter from '../design/exporter.js';
+import { getDesignCraftGuide } from '../design/craftguide.js';
 
 function text(str) {
   return { content: [{ type: 'text', text: str }] };
@@ -389,6 +390,68 @@ const HANDLERS = {
   },
   export_spec(args) { return json({ action: 'generate_spec', nodeId: args.nodeId, format: args.format || 'markdown' }); },
   export_changelog(args) { return json({ action: 'diff_frames', nodeIdA: args.nodeIdA, nodeIdB: args.nodeIdB, format: args.format || 'markdown' }); },
+
+  // ═══ DESIGN CRAFT ═══
+  get_design_craft_guide() {
+    return text(getDesignCraftGuide());
+  },
+
+  // ═══ CREATE (additional) ═══
+  create_ellipse(args) {
+    return json({
+      action: 'create_ellipse',
+      name: args.name || 'Ellipse',
+      width: args.width, height: args.height,
+      fill: args.fill || '#ffffff',
+      x: args.x, y: args.y,
+      parentId: args.parentId,
+      opacity: args.opacity,
+    });
+  },
+
+  create_line(args) {
+    var dir = args.direction || 'horizontal';
+    return json({
+      action: 'create_rect',
+      name: args.name || 'Divider',
+      width: dir === 'horizontal' ? args.length : 1,
+      height: dir === 'horizontal' ? 1 : args.length,
+      fill: args.color || '#1a1a32',
+      parentId: args.parentId,
+    });
+  },
+
+  create_svg_node(args) {
+    return json({
+      action: 'create_svg_node',
+      name: args.name || 'SVG',
+      svg: args.svg,
+      x: args.x, y: args.y,
+      parentId: args.parentId,
+    });
+  },
+
+  find_nodes(args) {
+    return json({
+      action: 'find_nodes',
+      query: args.query,
+      type: args.type,
+      parentId: args.parentId,
+    });
+  },
+
+  // ═══ TYPOGRAPHY (additional) ═══
+  style_text_range(args) {
+    return json({
+      action: 'style_text_range',
+      nodeId: args.nodeId,
+      start: args.start,
+      end: args.end,
+      fontSize: args.fontSize,
+      fontWeight: args.fontWeight,
+      color: args.color,
+    });
+  },
 };
 
 // ─── Helpers ───

package/src/tools/registry.js

@@ -5,9 +5,10 @@
 // Each tool has: name, description, category, inputSchema, handler reference.
 
 export const CATEGORIES = {
-  create:       { label: 'Create',          icon: '⊞', count: 8 },
+  craft:        { label: 'Design Craft',   icon: '✦', count: 1 },
+  create:       { label: 'Create',          icon: '⊞', count: 12 },
   layout:       { label: 'Layout',          icon: '▤', count: 7 },
-  typography:   { label: 'Typography',      icon: '◆', count: 6 },
+  typography:   { label: 'Typography',      icon: '◆', count: 7 },
   color:        { label: 'Color & Style',   icon: '◑', count: 7 },
   components:   { label: 'Components',      icon: '◎', count: 6 },
   spacing:      { label: 'Spacing & Grid',  icon: '◧', count: 6 },
@@ -26,16 +27,40 @@ function opt(schema) { return { ...schema, optional: true }; }
 export const TOOLS = [
   // ═══ CREATE ═══
   { name: 'create_frame', category: 'create',
-    description: 'Create an auto-layout frame with grid-aligned spacing, proper padding, and constraints.',
-    inputSchema: { type: 'object', properties: { name: str('Frame name'), width: opt(num('Width')), height: opt(num('Height')), direction: opt(str('horizontal or vertical')), padding: opt(num('Padding (snapped to grid)')), gap: opt(num('Gap (snapped to grid)')), fill: opt(str('Background color hex')) }, required: ['name'] } },
+    description: 'Create a single auto-layout frame. IMPORTANT: For multi-element designs (pages, sections, dashboards), use create_page or create_section instead — they handle all nesting automatically. If using create_frame directly, ALWAYS set parentId to nest inside a parent frame, and ALWAYS set direction, padding, and gap for auto-layout.',
+    inputSchema: { type: 'object', properties: { name: str('Frame name'), width: opt(num('Width')), height: opt(num('Height')), direction: opt(str('VERTICAL or HORIZONTAL')), padding: opt(num('Padding in px (use multiples of 8)')), paddingTop: opt(num('Top padding')), paddingBottom: opt(num('Bottom padding')), paddingLeft: opt(num('Left padding')), paddingRight: opt(num('Right padding')), gap: opt(num('Gap between children (use multiples of 8)')), fill: opt(str('Background color hex')), cornerRadius: opt(num('Corner radius')), parentId: opt(str('REQUIRED for nesting: parent frame ID')), primaryAxisAlignItems: opt(str('MIN, CENTER, MAX, SPACE_BETWEEN')), counterAxisAlignItems: opt(str('MIN, CENTER, MAX, STRETCH')), primaryAxisSizingMode: opt(str('FIXED, HUG, FILL')), counterAxisSizingMode: opt(str('FIXED, HUG, FILL')) }, required: ['name'] } },
 
   { name: 'create_page', category: 'create',
-    description: 'Create a full page from intent: landing, pricing, dashboard, settings, auth. Generates proper section hierarchy with auto-layout.',
-    inputSchema: { type: 'object', properties: { pageType: str('Page type: landing, pricing, dashboard, settings, auth, blog, portfolio, docs'), title: opt(str('Page title')), sections: opt(arr('Section types to include')), brandColor: opt(str('Primary brand color hex')), darkMode: opt(bool('Generate dark mode variant')) }, required: ['pageType'] } },
+    description: 'THE PRIMARY TOOL FOR DESIGNING PAGES. Creates a complete, polished, production-ready page with all sections, components, and content — fully nested with auto-layout, proper spacing, and design-intelligent values. One call generates 40-80 Figma elements. Use this INSTEAD of calling create_frame/create_text individually. Supports: landing, pricing, dashboard page types. Pass brand color, title, features, stats, and other content as parameters.',
+    inputSchema: { type: 'object', properties: {
+      pageType: str('Page type: landing, pricing, dashboard'),
+      title: opt(str('Hero heading text')),
+      subtitle: opt(str('Hero subtitle text')),
+      brand: opt(str('Brand/company name (appears in nav and footer)')),
+      brandColor: opt(str('Primary brand color hex (default #6366f1)')),
+      ctaText: opt(str('Primary CTA button text')),
+      darkMode: opt(bool('Dark mode (default true)')),
+      width: opt(num('Page width (default 1440)')),
+      navItems: opt(arr('Navigation link labels')),
+      features: opt(arr('Feature objects with icon, title, desc fields')),
+      stats: opt(arr('Stat objects with value and label fields')),
+      tiers: opt(arr('Pricing tier objects with name, price, period, desc, features, cta, highlighted fields')),
+      metrics: opt(arr('Dashboard metric objects with label, value, change, positive fields')),
+    }, required: ['pageType'] } },
 
   { name: 'create_section', category: 'create',
-    description: 'Create a page section: hero, features, testimonials, FAQ, CTA, pricing, stats, team. Pattern-aware with proper hierarchy.',
-    inputSchema: { type: 'object', properties: { sectionType: str('Section type: hero, features, testimonials, faq, cta, pricing, stats, team, footer, header'), heading: opt(str('Section heading')), content: opt(str('Content description')), columns: opt(num('Number of columns for grid sections')) }, required: ['sectionType'] } },
+    description: 'Creates a complete page section with all child elements, auto-layout, and proper nesting. One call generates 5-20 Figma elements. Use this INSTEAD of manually building sections. Supports: hero, features, pricing, cta, testimonials, faq section types.',
+    inputSchema: { type: 'object', properties: {
+      sectionType: str('Section type: hero, features, testimonials, faq, cta, pricing'),
+      heading: opt(str('Section heading')),
+      subheading: opt(str('Section subtitle')),
+      brandColor: opt(str('Brand color hex')),
+      ctaText: opt(str('CTA button text')),
+      width: opt(num('Section width (default 1440)')),
+      features: opt(arr('Feature objects for features section')),
+      testimonials: opt(arr('Testimonial objects with quote, author, role')),
+      faqs: opt(arr('FAQ objects with q and a fields')),
+    }, required: ['sectionType'] } },
 
   { name: 'create_card', category: 'create',
     description: 'Create a card with proper padding, radius, shadow depth, and content hierarchy.',
@@ -277,6 +302,33 @@ export const TOOLS = [
   { name: 'export_changelog', category: 'export',
     description: 'Diff two frames and export what changed as structured markdown or JSON.',
     inputSchema: { type: 'object', properties: { nodeIdA: str('First frame (before)'), nodeIdB: str('Second frame (after)'), format: opt(str('markdown or json')) }, required: ['nodeIdA', 'nodeIdB'] } },
+
+  // ═══ DESIGN CRAFT ═══
+  { name: 'get_design_craft_guide', category: 'craft',
+    description: 'CALL THIS FIRST before any design work. Returns professional design rules: typography scales, spacing systems (8px grid), color palettes, component patterns, and anti-patterns. Following these rules is the difference between amateur and production-quality output. Read the full guide before calling any create_ tools.',
+    inputSchema: { type: 'object', properties: {}, required: [] } },
+
+  // ═══ CREATE (additional) ═══
+  { name: 'create_ellipse', category: 'create',
+    description: 'Create a circle or oval. Use for avatars, status indicators, decorative elements, and icon backgrounds. Set equal width and height for a perfect circle.',
+    inputSchema: { type: 'object', properties: { name: opt(str('Element name')), width: num('Width in px'), height: num('Height in px'), fill: opt(str('Fill color hex')), x: opt(num('X position')), y: opt(num('Y position')), parentId: opt(str('Parent frame ID')), opacity: opt(num('Opacity 0-1')) }, required: ['width', 'height'] } },
+
+  { name: 'create_line', category: 'create',
+    description: 'Create a horizontal or vertical line. Use for dividers between sections, separators in navigation, and visual breaks. A line is a rectangle with 1px height (horizontal) or 1px width (vertical).',
+    inputSchema: { type: 'object', properties: { name: opt(str('Element name')), length: num('Length in px'), direction: opt(str('horizontal or vertical (default horizontal)')), color: opt(str('Line color hex')), parentId: opt(str('Parent frame ID')) }, required: ['length'] } },
+
+  { name: 'create_svg_node', category: 'create',
+    description: 'Create a vector graphic from raw SVG markup. Use for icons, logos, illustrations, and any custom vector shape. Pass the SVG string directly.',
+    inputSchema: { type: 'object', properties: { name: opt(str('Element name')), svg: str('Raw SVG markup string'), x: opt(num('X position')), y: opt(num('Y position')), parentId: opt(str('Parent frame ID')) }, required: ['svg'] } },
+
+  { name: 'find_nodes', category: 'create',
+    description: 'Search for elements by name or type within a frame or the entire page. Returns matching nodes with their IDs, positions, and basic properties. Use to locate elements before editing them.',
+    inputSchema: { type: 'object', properties: { query: opt(str('Search by name (partial match)')), type: opt(str('Filter by type: FRAME, TEXT, RECTANGLE, ELLIPSE, COMPONENT, INSTANCE')), parentId: opt(str('Search within this frame only')) }, required: [] } },
+
+  // ═══ TYPOGRAPHY (additional) ═══
+  { name: 'style_text_range', category: 'typography',
+    description: 'Apply different styles to specific character ranges within a text node. Use for mixed-weight text (e.g., bold product name within a regular sentence), colored keywords, or size variations within a single text element.',
+    inputSchema: { type: 'object', properties: { nodeId: str('Text node ID'), start: num('Start character index'), end: num('End character index'), fontSize: opt(num('Font size for range')), fontWeight: opt(num('Font weight: 400, 500, 600, 700')), color: opt(str('Color hex for range')) }, required: ['nodeId', 'start', 'end'] } },
 ];
 
 export function getToolsByCategory(category) {