sammyai

Sammy

Sammy is a Manifest V3 Chrome extension that connects Figma and JIRA workflows. It can analyze a captured Figma frame, turn the result into a structured story, push tickets to JIRA, round-trip ticket data back into Figma, and optionally generate starter UI code from the same design context.

Current status

See PROJECT_STATUS.md for an always-on snapshot of what works today, what is missing, and the next pieces of work.

Prerequisites

Sammy is a bring-your-own-keys tool. Before using any workflow you will need the following credentials:

• AI provider – OpenAI or Anthropic API key stored via the settings page (openaiKey / claudeKey).
• Figma access – a personal access token and an optional development plugin ID if you want to use the richer plugin integration.
• JIRA access – domain, email, API token, and default project key so the background worker can call the REST API.

All configuration happens in the options UI (settings.html/settings.js) and is saved to Chrome sync storage for reuse across devices.

Getting started

1. Clone the repository and run npm install.
2. Load the sammyai directory as an unpacked extension from chrome://extensions.
3. Open the extension options page and paste your API keys plus any Figma/JIRA metadata.
4. (Optional) Import the figma-plugin/manifest.json into Figma development mode and record the plugin ID so enhanced design data can flow back to the extension.

Key workflows

Figma → JIRA story generation

• The content script listens for activation inside figma.com, captures the frame, and sends a request to the service worker with screenshot, optional context, and any structured layer data it can collect.
• background.js builds a prompt that blends screenshot, Figma REST/plugin data, and user context. It can call either OpenAI or Anthropic based on the saved provider and normalises the JSON response into title, description, and acceptanceCriteria fields.

JIRA → Figma design generation (Stock UI)

• The MCP bridge server (sammy-mcp/) provides a specialized endpoint for generating Figma design plans from Portfolio-OS Jira issues.
• Use POST /api/stock-ui/generate with an array of Jira issue keys to automatically generate design plans using the stock-ui-scaffold prompt.
• Each design plan is sent to the Figma plugin for automatic frame creation, ensuring compliance with the Portfolio-OS data contract and visual language.

JIRA → Figma frame generation

• The background worker can ingest a ticket payload, enrich it with any attachments, and ask OpenAI to return Figma node JSON that represents a scaffolded mock.
• It opens the configured Figma file with the Sammy plugin URL so the plugin can materialise the design plan inside Figma.

Code generation

• The story editor in the content script can launch a language picker that forwards rich design data (plugin payload, screenshot, story) to the background worker.
• The worker instantiates the appropriate generator (React, SwiftUI, or Kotlin) via lib/codegen/generator-factory.js and uses the selected AI provider to produce a code snippet.
• Generated code is shown in a modal with copy and download helpers so you can paste it into your project.

Running tests

• npm test – runs the Vitest unit suite (default configuration).
• npm run test:integration – executes integration specs for the bridge server and provider abstractions.
• npm run test:e2e – launches the Playwright extension tests.

The unit suite stubs Chrome APIs so the background worker, analytics helpers, and code generation classes can be exercised without a browser. Integration tests cover the MCP bridge that turns JIRA tickets into Figma plans.

Repository layout

• background.js, content.js, popup.html/js, settings.html/js – extension entry points.
• lib/ – shared logic for AI providers, analytics, code generation, and design quality scoring.
• figma-plugin/ – companion plugin that streams rich design data to the extension and builds frames from generated plans.
• sammy-mcp/ – Model Context Protocol bridge used by the JIRA → Figma workflow.
• tests/ – Vitest unit/integration specs and Playwright E2E coverage.
• scripts/ – packaging, version bumping, and other operational helpers.

Support & licensing

The extension is released under the MIT license. File issues or ideas in the repository and run the provided tests before submitting pull requests.