@salesforce/afv-skills 1.7.5 → 1.9.0

package/skills/generating-visual-diagrams/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: generating-visual-diagrams
+description: "AI-powered image generation for Salesforce visuals via Nano Banana Pro. Use this skill when the user needs rendered PNG/SVG output such as visual ERDs (Entity Relationship Diagrams), UI mockups, wireframes, or architecture illustrations. TRIGGER when: user asks for PNG/SVG output, UI mockups, wireframes, visual ERDs, or says \"generate image\" / \"create mockup\". DO NOT TRIGGER when: text-based Mermaid diagrams (use generating-mermaid-diagrams), or non-visual documentation tasks."
+license: MIT
+metadata:
+  version: "1.0"
+---
+
+# generating-visual-diagrams: Salesforce Visual AI Skill
+
+Use this skill when the user needs **rendered visuals**, not text diagrams: ERDs, UI mockups, architecture illustrations, slide-ready images, or image edits using Nano Banana Pro.
+
+## Scope
+
+**In scope:**
+- PNG / SVG-style rendered image output
+- Visual ERDs and architecture diagrams
+- LWC or Experience Cloud mockups / wireframes
+- Image edits on previously generated visuals
+
+**Out of scope — delegate instead:**
+- Mermaid or text-only diagrams → [generating-mermaid-diagrams](../generating-mermaid-diagrams/SKILL.md)
+- Object / field metadata discovery for ERDs → [generating-custom-object](../generating-custom-object/SKILL.md) or [generating-custom-field](../generating-custom-field/SKILL.md)
+- LWC implementation after the mockup is approved → [generating-lwc-components](../generating-lwc-components/SKILL.md)
+- Apex review / implementation → [generating-apex](../generating-apex/SKILL.md)
+
+---
+
+## Hard Gate: Prerequisites First
+
+Run the prerequisites check before using the skill:
+
+```bash
+scripts/check-prerequisites.sh
+```
+
+If prerequisites fail, stop and route the user to setup guidance in:
+- [references/gemini-cli-setup.md](references/gemini-cli-setup.md)
+
+---
+
+## Required Inputs
+
+Ask for or infer before generating:
+
+| Input | Default if not provided |
+|---|---|
+| Image type | ERD |
+| Subject scope and key entities / systems | Ask the user |
+| Target quality | Draft (1K) |
+| Preferred style | architect.salesforce.com aesthetic |
+| Aspect ratio | Default (no override) |
+| Quick mode or interview mode | Interview mode |
+
+---
+
+## Interview-First Workflow
+
+Unless the user asks for **quick / simple / just generate**, ask clarifying questions first using the question bank in [references/interview-questions.md](references/interview-questions.md).
+
+| Request type | Ask about |
+|---|---|
+| ERD / schema | objects, visual style, purpose, extras |
+| UI mockup | component type, object/context, device/layout, style |
+| architecture image | systems, boundaries, protocols, emphasis |
+| image edit | what to keep, what to change, output quality |
+
+**Quick mode defaults** (triggered by "quick", "simple", "just generate", "fast"):
+- professional style, 1K draft, legend included, one image first then iterate
+
+---
+
+## Recommended Workflow
+
+### 1. Run prerequisites check
+Run `scripts/check-prerequisites.sh` and confirm all required tools pass before proceeding.
+
+### 2. Gather inputs
+- object list / metadata (delegate to `generating-custom-object` / `generating-custom-field` if needed)
+- purpose: draft vs presentation vs documentation
+- desired aesthetic — read [references/architect-aesthetic-guide.md](references/architect-aesthetic-guide.md) for ERDs
+- aspect ratio / resolution
+
+### 3. Run interview or use quick-mode defaults
+Load [references/interview-questions.md](references/interview-questions.md) for the matching question set (ERD, LWC, architecture, code review).
+
+### 4. Build a concrete prompt
+Good prompts specify subject, composition, color treatment, labels/legends, and output quality goal.
+
+### 5. Generate a fast draft at 1K
+```bash
+gemini --yolo "/generate 'Your prompt here'"
+```
+Open the result and review layout before spending on higher resolution.
+
+### 6. Iterate using edits
+```bash
+gemini --yolo "/edit 'Specific change instruction'"
+```
+Use `/edit` for small adjustments — cheaper than regenerating. See [references/iteration-workflow.md](references/iteration-workflow.md).
+
+### 7. Generate final at 2K/4K using the Python script
+Run `scripts/generate_image.py` when layout is confirmed:
+```bash
+uv run scripts/generate_image.py -p "Refined prompt" -f "output.png" -r 4K
+```
+
+### 8. Error recovery
+- If `gemini --yolo` returns no image: re-run once; if it fails again, fall back to the Python script path.
+- If the Python script fails with `GEMINI_API_KEY not found`: verify the key is exported in your shell profile (`~/.zshrc` on macOS/zsh, `~/.bashrc` on Linux) and the terminal session is refreshed.
+- If the extension is missing: run `gemini extensions install nanobanana` and re-run the prerequisites check.
+
+---
+
+## Default Style Guidance
+
+For ERDs, default to the **architect.salesforce.com** aesthetic unless the user asks otherwise:
+- dark border + light fill cards
+- cloud-specific accent colors
+- clean labels and relationship lines
+- presentation-ready whitespace and hierarchy
+
+Full style specification: [references/architect-aesthetic-guide.md](references/architect-aesthetic-guide.md)
+
+---
+
+## Common Patterns
+
+| Pattern | Default approach |
+|---|---|
+| visual ERD | get metadata if available, then render a draft first |
+| LWC mockup | load [assets/lwc/data-table.md](assets/lwc/data-table.md), [assets/lwc/record-form.md](assets/lwc/record-form.md), or [assets/lwc/dashboard-card.md](assets/lwc/dashboard-card.md) for the matching template |
+| architecture illustration | load [assets/architecture/integration-flow.md](assets/architecture/integration-flow.md); emphasize systems and flows |
+| image refinement | use `/edit` for small changes before regenerating |
+| final production asset | switch to script-driven 2K/4K generation via `scripts/generate_image.py` |
+| Apex / LWC code review | load [assets/review/apex-review.md](assets/review/apex-review.md) or [assets/review/lwc-review.md](assets/review/lwc-review.md) for the review prompt template |
+
+---
+
+## Output Expectations
+
+Deliverables produced by this skill:
+
+- **Draft image** (`<name>.png`) — 1K resolution rendered via `gemini --yolo "/generate ..."` for layout review
+- **Final image** (`<name>.png`) — 2K or 4K resolution rendered via `scripts/generate_image.py` once composition is approved
+- **Edit iteration** (`<name>.png`) — incremental refinement via `gemini --yolo "/edit ..."` without full regeneration
+
+After delivering each image:
+- Open the file in Preview or attach it in the session for multimodal review
+- Ask the user whether to iterate on layout, labeling, or color before finalizing
+- Only proceed to high-res output after draft composition is confirmed
+
+---
+
+## Rules / Constraints
+
+| Rule | Rationale |
+|---|---|
+| Always run prerequisites check before any generation | Missing tools produce silent failures |
+| Always draft at 1K before generating at 4K | Cost and time savings; composition changes at high res are wasteful |
+| Use `/edit` for incremental changes, not full regeneration | Cheaper and faster for small adjustments |
+| Never commit `GEMINI_API_KEY` to version control | Key is personal and tied to billing |
+| Delegate text diagrams to `generating-mermaid-diagrams` | This skill owns rendered images only |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| Edit not applying correctly | Be specific: reference existing elements by name; one change at a time |
+| 4K output looks different from 1K draft | Use exact same prompt text; minor variations are normal model behavior |
+| `gemini --yolo` fails silently | Check that the Nano Banana extension is installed: `gemini extensions list` |
+| Image dimensions wrong | Set `--aspect-ratio` explicitly in `scripts/generate_image.py` using `-a "16:9"` |
+| RGBA image causes errors in Python script | Script auto-converts RGBA→RGB; ensure Pillow is installed via `uv` |
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to | Reason |
+|---|---|---|
+| Mermaid first draft or text diagram | [generating-mermaid-diagrams](../generating-mermaid-diagrams/SKILL.md) | faster structural diagramming |
+| Object / field discovery for ERD | [generating-custom-object](../generating-custom-object/SKILL.md) / [generating-custom-field](../generating-custom-field/SKILL.md) | accurate schema grounding |
+| Turn mockup into real LWC component | [generating-lwc-components](../generating-lwc-components/SKILL.md) | implementation after design |
+| Apex review / implementation | [generating-apex](../generating-apex/SKILL.md) | code-quality follow-up |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| [references/gemini-cli-setup.md](references/gemini-cli-setup.md) | Prerequisites fail — Gemini CLI / Nano Banana setup guidance |
+| [references/interview-questions.md](references/interview-questions.md) | Step 3 — load question set matching the request type |
+| [references/iteration-workflow.md](references/iteration-workflow.md) | Step 6 — draft-to-final iteration patterns and cost tips |
+| [references/architect-aesthetic-guide.md](references/architect-aesthetic-guide.md) | Step 4 — ERD color palettes, box styles, prompt templates |
+| [references/examples-index.md](references/examples-index.md) | Step 4 — example prompts for ERD, LWC, architecture, code review |
+| [assets/erd/core-objects.md](assets/erd/core-objects.md) | Step 4 — prompt template for core CRM objects (Account, Contact, Opportunity, Case) |
+| [assets/erd/custom-objects.md](assets/erd/custom-objects.md) | Step 4 — prompt template for custom object ERDs |
+| [assets/lwc/data-table.md](assets/lwc/data-table.md) | Step 4 — prompt template for lightning-datatable mockups |
+| [assets/lwc/record-form.md](assets/lwc/record-form.md) | Step 4 — prompt template for lightning-record-form mockups |
+| [assets/lwc/dashboard-card.md](assets/lwc/dashboard-card.md) | Step 4 — prompt template for dashboard card / metric tile mockups |
+| [assets/architecture/integration-flow.md](assets/architecture/integration-flow.md) | Step 4 — prompt template for integration architecture diagrams |
+| [assets/review/apex-review.md](assets/review/apex-review.md) | Step 4 — Gemini review prompt template for Apex code |
+| [assets/review/lwc-review.md](assets/review/lwc-review.md) | Step 4 — Gemini review prompt template for LWC components |
+| [scripts/check-prerequisites.sh](scripts/check-prerequisites.sh) | Step 1 — run to verify all required tools are installed |
+| [scripts/generate_image.py](scripts/generate_image.py) | Step 7 — run for 2K/4K resolution output and image editing with resolution control |

package/skills/generating-visual-diagrams/assets/architecture/integration-flow.md

@@ -0,0 +1,55 @@
+# Architecture Template: Integration Flow
+
+## Prompt Template
+
+```
+Professional Salesforce integration architecture diagram:
+
+SYSTEMS:
+[List systems with types and icons]
+
+INTEGRATION PATTERNS:
+[List integrations with protocols and directions]
+
+COMPONENTS:
+- API Gateway (if applicable)
+- Authentication layer
+- Middleware/ESB (if applicable)
+- Error handling/retry logic
+
+STYLING:
+- Cloud icon for Salesforce
+- Server icons for external systems
+- Arrows with protocol labels
+- Color coding by system type
+- Professional diagram style
+
+FORMAT:
+- Landscape orientation
+- Left-to-right or hub-spoke layout
+- Include legend
+```
+
+## Example
+
+```bash
+gemini "/generate 'Salesforce integration architecture diagram:
+
+Systems:
+1. Salesforce (cloud icon, blue)
+2. MuleSoft (middleware icon, purple)
+3. SAP ERP (server icon, orange)
+
+Flows:
+1. Salesforce --REST--> MuleSoft --BAPI--> SAP
+   - Account/Contact sync (bidirectional)
+
+2. SAP --Events--> MuleSoft --Platform Events--> Salesforce
+   - Invoice updates
+
+Include:
+- OAuth 2.0 authentication badges
+- Error queue for failed messages
+
+Style: Professional, clean lines, pastel colors'"
+```

package/skills/generating-visual-diagrams/assets/erd/core-objects.md

@@ -0,0 +1,131 @@
+# ERD Template: Core Salesforce Objects (Architect.salesforce.com Style)
+
+## Default Style
+
+All ERDs now use the **official architect.salesforce.com aesthetic** by default:
+- Dark border + light translucent fill boxes
+- Header banner with Salesforce logo
+- LEGEND bar with ENTITIES and RELATIONSHIPS
+- Labeled relationship lines
+- Footer with copyright
+
+See `references/architect-aesthetic-guide.md` for full specification.
+
+---
+
+## Prompt Template (Architect.salesforce.com Style)
+
+```
+Create a Salesforce Core CRM ERD in the EXACT architect.salesforce.com style:
+
+PAGE TITLE (very top, large bold text):
+'Core CRM Overview Data Model'
+
+HEADER SECTION (below title):
+- Left: Salesforce cloud logo + 'SALESFORCE PLATFORM Overview' in dark teal (#0B827C) banner box
+- Center: LEGEND with 'ENTITIES' section showing:
+  * Cloud Entity box (dark teal #0B827C border, light teal ~25% opacity fill)
+  * Related Entity box (dark teal border, lighter fill)
+  * External Entity box (black border, white fill)
+- Right: 'RELATIONSHIPS' section showing notation symbols for Parent/Child, Required, Optional, Many-to-Many
+
+BOX STYLING - CRITICAL:
+- DARK BORDER: Solid 2px border in dark teal (#0B827C)
+- LIGHT TRANSLUCENT FILL: Same teal hue at ~25% opacity
+- Rounded corners (8-12px radius)
+- Text in dark gray/black on the light fill
+
+ENTITY BOX FORMAT:
+┌─────────────────────────┐
+│ Logical Name            │  (Bold, larger)
+│ APIName                 │  (Smaller, italic, gray)
+│ • Field1                │  (Bullet points)
+│ • Field2                │
+└─────────────────────────┘
+
+OBJECTS TO INCLUDE (all with dark teal border + light teal fill):
+
+- Account (center position):
+  Account
+  Account
+  • Account Number
+  • Name
+  • Industry
+  • Type
+
+- Contact (linked to Account):
+  Contact
+  Contact
+  • Name
+  • Email
+  • Title
+  • Phone
+
+- Opportunity (linked to Account):
+  Opportunity
+  Opportunity
+  • Name
+  • Amount
+  • Close Date
+  • StageName
+
+- Case (linked to Account and Contact):
+  Case
+  Case
+  • CaseNumber
+  • Type
+  • Priority
+  • Status
+
+RELATIONSHIP LINES:
+- Thin black lines with text labels ON the lines
+- Contact → Account: "child of" (crow's foot on Contact side)
+- Opportunity → Account: "child of" (crow's foot on Opportunity side)
+- Case → Account: "related to" (crow's foot on Case side)
+- Case → Contact: "related to" (optional)
+- STRAIGHT LINES ONLY (horizontal and vertical, no diagonals)
+
+FOOTER:
+Left: '©2024 Salesforce - Subject to change without notice'
+Right: 'Last modified: [current date]'
+
+CRITICAL: Dark teal borders with LIGHT translucent teal fill - NOT solid filled boxes.
+```
+
+---
+
+## Usage
+
+```bash
+# Quick draft at 1K (iterate here)
+gemini --yolo "/generate '[paste prompt above]'"
+open ~/nanobanana-output/*.png  # Review and refine
+
+# Final at 4K (when satisfied)
+uv run scripts/generate_image.py \
+  -p "[your refined prompt]" \
+  -f "core-crm-erd.png" \
+  -r 4K
+open ~/nanobanana-output/*core-crm*.png
+```
+
+---
+
+## Cloud Color Reference
+
+| Cloud | Border Color | Fill (~25% opacity) |
+|-------|--------------|---------------------|
+| Sales Cloud | `#0B827C` (Teal) | Light Teal |
+| Service Cloud | `#9E2A7D` (Magenta) | Light Pink |
+| Platform | `#5A67D8` (Purple) | Light Purple |
+
+---
+
+## Resolution Guide
+
+| Phase | Resolution | Use Case |
+|-------|------------|----------|
+| Draft | 1K (CLI) | Quick iteration, prompt refinement |
+| Final | 4K (Python) | Documentation, presentations |
+
+**Tip**: Iterate at 1K until layout is correct, then generate 4K final.

package/skills/generating-visual-diagrams/assets/erd/custom-objects.md

@@ -0,0 +1,60 @@
+# ERD Template: Custom Objects
+
+## Prompt Template
+
+```
+Professional Salesforce ERD diagram showing custom objects:
+
+OBJECTS:
+[List custom objects with relationships]
+
+COLOR CODING:
+- Standard Objects: Blue (#bae6fd fill, #0369a1 border)
+- Custom Objects: Orange (#fed7aa fill, #c2410c border)
+- External Objects: Green (#a7f3d0 fill, #047857 border)
+
+RELATIONSHIPS:
+- Lookup (LK): Dashed arrow, optional parent
+- Master-Detail (MD): Solid thick arrow, cascade delete
+
+STYLING:
+- Clean white background
+- Pastel fill colors with dark borders
+- Relationship labels on arrows
+- Professional diagram layout
+- Include color legend
+
+FORMAT:
+- Auto-layout based on relationships
+- Primary objects centered
+- Child objects positioned below/right of parents
+```
+
+## Example
+
+```bash
+# Draft at 1K (iterate here)
+gemini --yolo "/generate 'Salesforce ERD for real estate app:
+- Property__c (orange, center): Main custom object
+- Listing__c (orange, right): Master-Detail to Property__c
+- Showing__c (orange, below): Lookup to both Property__c and Contact
+
+Orange boxes for custom objects, blue for standard (Contact).
+Include legend. Professional style.'"
+open ~/nanobanana-output/*.png  # Review and refine
+
+# Final at 4K (when satisfied)
+uv run scripts/generate_image.py \
+  -p "Salesforce ERD for real estate app..." \
+  -f "realestate-erd.png" \
+  -r 4K
+```
+
+## Resolution Guide
+
+| Phase | Resolution | Use Case |
+|-------|------------|----------|
+| Draft | 1K (CLI) | Quick iteration, prompt refinement |
+| Final | 4K (Python) | Documentation, presentations |
+
+**Tip**: Iterate at 1K until layout is correct, then generate 4K final.

package/skills/generating-visual-diagrams/assets/lwc/dashboard-card.md

@@ -0,0 +1,45 @@
+# LWC Template: Dashboard Card Mockup
+
+## Prompt Template
+
+```
+Salesforce Lightning dashboard card/tile mockup:
+
+CARD TYPE: [metric/chart/list/progress]
+
+METRIC CARD:
+- Large metric value
+- Label below
+- Trend indicator: up/down arrow with percentage
+- Sparkline mini chart (optional)
+- Icon in corner
+
+CHART CARD:
+- Chart type: [bar/line/pie/donut]
+- Legend position
+- Data labels on hover
+
+LIST CARD:
+- Title with "View All" link
+- 3-5 list items
+- Each item: icon, primary text, secondary text
+
+STYLING:
+- SLDS card component
+- White background with subtle shadow
+- Rounded corners
+- Header with title and action menu
+```
+
+## Example: Metric Card
+
+```bash
+gemini "/generate 'Salesforce dashboard metric card:
+- Large number: $1.2M
+- Label: Total Pipeline Value
+- Trend: +12% (green up arrow)
+- Icon: Opportunity icon (top-right)
+- Sparkline: Show 7-day trend mini chart
+
+Style: SLDS card, white background, subtle shadow'"
+```

package/skills/generating-visual-diagrams/assets/lwc/data-table.md

@@ -0,0 +1,57 @@
+# LWC Template: Data Table Mockup
+
+## Prompt Template
+
+```
+Salesforce Lightning Web Component data table mockup:
+
+COMPONENT: lightning-datatable style
+
+HEADER:
+- Component title: "[Title]"
+- Search box (right-aligned)
+- Action buttons: New, Refresh, Export
+
+COLUMNS:
+[List columns with types]
+
+SAMPLE DATA:
+- Show 5-7 sample rows with realistic data
+- Include row selection checkboxes
+- Show sorting arrows on sortable columns
+
+STYLING:
+- SLDS (Salesforce Lightning Design System)
+- Zebra striping on rows
+- Hover highlight
+- Blue header bar
+- White background
+
+ACTIONS:
+- Row-level action menu (three dots)
+- Bulk action buttons when rows selected
+
+FORMAT:
+- Desktop view (1200px width)
+- Full component with card wrapper
+- Include pagination footer
+```
+
+## Example
+
+```bash
+gemini "/generate 'Salesforce LWC data table mockup:
+Title: Recent Opportunities
+Columns:
+1. Opportunity Name (link)
+2. Account Name (text)
+3. Amount (currency, right-aligned)
+4. Stage (picklist badge)
+5. Close Date (date)
+6. Owner (user with avatar)
+
+Sample data: Show 5 realistic opportunities
+Include: Search, New button, row actions menu
+Style: SLDS, professional, clean
+Pagination: 1-5 of 127'"
+```

package/skills/generating-visual-diagrams/assets/lwc/record-form.md

@@ -0,0 +1,60 @@
+# LWC Template: Record Form Mockup
+
+## Prompt Template
+
+```
+Salesforce Lightning Web Component record form mockup:
+
+COMPONENT: lightning-record-form style
+
+HEADER:
+- Object icon and label
+- Edit/Save/Cancel buttons (right)
+- Record name as title
+
+LAYOUT:
+- Two-column layout for desktop
+- Responsive single column for mobile
+
+SECTIONS:
+[Define sections with fields]
+
+FIELD TYPES:
+- Text inputs with labels above
+- Picklists as dropdown
+- Lookups with search icon
+- Date pickers with calendar
+- Currency with formatting
+- Checkboxes for boolean
+
+STYLING:
+- SLDS record page styling
+- Compact spacing
+- Blue section headers
+- Required field indicators (*)
+- Help text icons where applicable
+```
+
+## Example
+
+```bash
+gemini "/generate 'Salesforce LWC record form mockup:
+Object: Opportunity
+Mode: Edit
+
+Sections:
+1. Opportunity Information:
+   - Opportunity Name* (text)
+   - Account Name* (lookup with search)
+   - Type (picklist)
+   - Lead Source (picklist)
+
+2. Amount & Dates:
+   - Amount (currency)
+   - Close Date* (date picker)
+   - Stage* (picklist)
+   - Probability (percentage)
+
+Footer: Save and Cancel buttons
+Style: SLDS, professional, desktop view'"
+```

package/skills/generating-visual-diagrams/assets/review/apex-review.md

@@ -0,0 +1,57 @@
+# Apex Code Review Template
+
+## Gemini Review Prompt
+
+```
+Review this Apex code for best practices and issues:
+
+CODE:
+[paste code here]
+
+REVIEW CATEGORIES:
+
+1. BULKIFICATION
+   - SOQL queries in loops
+   - DML operations in loops
+   - Governor limit risks
+   - Collection usage
+
+2. SECURITY
+   - CRUD permissions check
+   - FLS enforcement
+   - Sharing model compliance
+   - Injection vulnerabilities
+
+3. BEST PRACTICES
+   - Trigger handler pattern
+   - One trigger per object
+   - Separation of concerns
+   - Proper exception handling
+
+4. PERFORMANCE
+   - Selective SOQL queries
+   - Index usage
+   - Unnecessary computation
+
+5. MAINTAINABILITY
+   - Code comments
+   - Method length
+   - Test coverage considerations
+
+OUTPUT FORMAT:
+JSON with summary, issues array, bestPractices array, and score
+```
+
+## Usage
+
+```bash
+gemini "Review this Apex trigger for issues: [paste code]" -o json
+```
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| High | Security, governor limits, data integrity |
+| Medium | Performance, best practices |
+| Low | Style, minor improvements |