All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
3.1.1 - 2026-08-31
-
figma.mcp.urlis now screened before it reaches the MCP probe. The value was read from the committedfigma.projects.config.jsonwithout validation and handed tocurlin URL position, so a value starting with-was parsed as an OPTION instead:-K<path>loads an arbitrary curl config file, which an attacker could commit beside it to obtainoutput(arbitrary file write with attacker-chosen content, i.e. code execution on the next run) orupload-file. The probe path is automatic — the mandatorybefore_specify/before_planhooks reach it throughfigma-ensure-context→figma-introspect→figma_resolve_context_source— so a hostile config in a cloned or PR-modified repository needed no user action beyond an ordinary SpecKit run.mcp.urlmust now carry anhttp(s)://scheme (newfigma_mcp_url_allowed/Test-FigmaMcpUrlAllowedguard, enforced at the probe and byfigma-validate-config, plus apatternin the JSON schema), and the probe passes it after a--separator. This closes the same class of holeapiBaseUrlwas already protected against.The host stays unrestricted, unlike
apiBaseUrl: no credential travels with the probe, so a self-hosted MCP server (devcontainer, tunnel, alternate port) keeps working. Figma links pasted into a prompt are unaffected — they are parsed for their file/node ids and never used as a request target.The one legitimate config this can reject is a scheme-less
mcp.url(e.g.127.0.0.1:3845/mcp), which curl used to accept by assuminghttp. Prefix it withhttp://and it works as before.
3.1.0 - 2026-08-25
- Cross-file source-component resolution.
figma-introspectused to resolve anINSTANCE's source component only against the file of the pinned link — a component published from another file (a Design System library, another project, another team) silently degraded to instance-only data. It now falls back to Figma's own component registry (GET /v1/components/{key}), which answers with the file that actually owns a published component regardless of where that is — no config has to name it up front, and the same lookup covers the Design System and any other library uniformly. Resolved components are recorded in a newsources.externalFilesmap; the rendered "Source components" table now shows aFilecolumn (same fileor`<fileKey>` (external)).designSystemalso gains optionalfigmaProjectId/figmaTeamId/figmaTeamIdsfields, for enumerating a Design System spread across several files when browsing its reuse inventory. - Content-aware component locator inside a
broad/oversizedlink. When the developer names or describes a specific component inside a page-sized link instead of asking "what's on this page?", the agent now searches the already-fetched subtree (node names,TEXTnode content) for a match and presents that single match for confirmation, instead of the raw list of top-level children. Documentation-only change (/speckit.figma.ensuresection 3b,/speckit.figma.introspectsection 3) — no new script.
- A component whose source could not be resolved at all (neither in the linked file nor in another one) no longer shows up as a blank, misleading row in the "Source components" table — it is dropped instead of looking like a resolved component with no name.
3.0.0 - 2026-08-24
- BREAKING (prerequisite) — the extension now requires SpecKit
>=0.11.2, up from>=0.1.0./speckit.convergeis the only reason: its command template, and therefore thebefore_converge/after_convergehook points, first ship in that release. Every other hook this extension registers has existed since at least v0.9.5. An install on an older SpecKit that worked before is now refused, so this is a real prerequisite tightening, not a silent minor — upgrade SpecKit (uv tool upgrade specify-cli) before updating the extension.
-
/speckit.figma.export— Figma nodes to image files, in two modes. One endpoint, two needs whose lifecycles are opposite, so they are separate modes rather than one flag that would put throwaway files under version control (or leave deliverables in a git-ignored cache).preview(default) renders the candidate frames to PNG underspecs/<feature>/assets/, so design rule 5 can be answered by looking at the creative instead of reading a list of node ids. Those files are committed on purpose:.figma/cache/is git-ignored, so a preview written there is invisible to a reviewer on GitHub andspec.mdrenders a broken image — a few tens of KB costs less than that.assetpulls what the implementation ships — a logo as.svg, a mock as.png.--outis mandatory: where a shipped asset belongs (Design System vs app) is a placement decision like any other, and the script refuses to guess it. A.figma-assets.jsonmanifest beside the files records what was written and its checksum, so a re-run reportsunchangedinstead of re-downloading and refuses to overwrite a file a human edited since (skipped-modified);--forceis how a developer says they meant it.Mechanics worth knowing: the endpoint renders asynchronously — it returns temporary URLs that must then be downloaded, two steps — ids are requested in batches (
--batch-size, default 10) because a large request times out on a big file,scaleis dropped for vector formats instead of being sent and rejected, and the rendered URL is a signed CDN link that is downloaded without the PAT, since attaching it would leak the credential to a third-party host. Export needs no scope beyondfile_content:read. The command is deliberately not hooked: it writes into the repository. -
Source components are resolved automatically — "right-click > show source". A linked node is almost always an
INSTANCE, and an instance is the flattened rendering of a main component: overrides applied, variant fixed. Reading it is how a spec ends up describing one particular appearance of a component rather than the component, which is what forced a developer to redo a feature in a second session, manually pasting the main component's node id into the spec.Introspection now collects the
componentIdof everyINSTANCEin the fetched subtrees and deep-fetches those definitions into a newsourcesslot on the snapshot. The rendered section lists them and tags every extracted value rowinstanceorsource, so a difference between the two stays visible as an override to expose as a prop instead of being silently merged into one number. Components living in another library file are out of reach (that would need the library's file key) and the resolution is non-fatal: a missing source degrades the context, it does not invalidate it. -
New
oversizedlink scope — a pinned node id is not automatically a creative.linkScopewas binary:broad(a file/page link) orframe(anything with a node id). A link copied from a full-page desktop frame pins aFRAMElike any other, so it was classifiedframe— a confirmed creative — and the confirmation checkpoint never fired. The agent then reasoned over 12 000 px of page as if it were the component, which is the single most expensive failure this extension has produced.A pinned node past
FIGMA_OVERSIZED_HEIGHT(3000px) orFIGMA_OVERSIZED_DESCENDANTS(150) is nowoversizedand handled exactly likebroad— enumerate and confirm — except the candidates are the node's own children: the developer linked the right page, they only have to say which block of it. Both thresholds are env-overridable, because "page-sized" is a property of the design system in use, not a universal constant. -
Deterministic design values in the rendered section. The renderer's stated goal is a section produced "REGARDLESS of the agent model" — but that was only ever true of its structure. The values were not: the snapshot is a raw dump of the Figma node tree (megabytes for a full-page frame) and the spacing/typography tables were left for the model to mine out of it. Weaker models do not mine megabytes of JSON; they guess, which is why a faithful-looking spec produced an implementation whose padding, alignment and type matched nothing in the mockup.
A new
figma-extract-valueshelper walks the deep-fetched nodes and emits the facts as a compact digest —layoutMode, the four paddings,itemSpacing, both axis alignments, corner radius, box size, and per text node the family, weight, size, line height, letter spacing and alignment, plus thestylesids that bridge to the Design System.figma-render-sectionnow pastes those as two tables inside the section, so the agent copies numbers instead of inventing them. Nodes carrying no design value contribute no row, and a padding Figma never sent is absent rather than fabricated as0px— a fabricated zero reads as a deliberate design decision the mockup never made. -
Units are always explicit, and the conversion contract is the project's. Every length is emitted as
70px, never as a bare70. A bare number is what lets a length be re-read as something else downstream: handed to a scale-indexed helper — Tailwind'smt-70, or MUI'stheme.spacing(70)on a theme built withspacing: 4— a 70px margin silently becomes 280px, wrong by the scale factor, with nothing failing.The extension deliberately stops at "this is 70 absolute CSS px at 1x". It does not convert, and there is no
unitsblock in the config: no schema could cover MUIuseStyleswith a custompxToRem, Tailwind, CSS variables, styled-components and vanilla-extract at once, and a half-covering one is worse than none. New base rule 6b states the invariant and the prohibition, and defers the conversion contract to the project overlay (.figma/figma-design-rules.custom.md) — the same pattern rule 4 already uses for the responsive policy.config/figma-design-rules.custom.example.mdships a ready-to-uncomment example that names the trap with the actual number. -
autoIntrospect— opt-in autonomous introspection, per target. 2.0.0 made a Figma link the sole trigger, which removed the agent's ability to fetch design context when it judges the feature to need it. A target can now re-open the config-derived path infigma.projects.config.json:offis the default, so nothing changes for a workspace that says nothing and the 2.0.0 contract is preserved.on-request(recommended) has the committed config authorise and the agent trigger, by passing the new--assume-designflag when the feature plainly describes UI work; on a target left atoffthe flag is ignored with a warning, so an agent can never grant itself design context.alwaysrestores the pre-2.0.0 behaviour for the targets that want it.Three properties keep this from re-creating the regression 2.0.0 removed:
- The autonomous path introspects the mapped file and nothing wider. A
project or team id would crawl an organisation — that is
/speckit.figma.introspect's job, never an automatic pre-generation hook's. A target with nofigmaFileIdreports the new reasonauto-unavailable, and the schema refuses the combination outright. maxFrames(default 60) is a hard, measured budget. Over it, the run stops attoo-large-for-autowith nothing rendered and asks for a node id, because context that wide is too diluted to implement faithfully. It is checked at all three points that reach a usable snapshot — the fresh slot, the restored per-file copy and a fresh introspection — and never applies to a link-driven run, whose node id already pins the creative.- The rule-5 confirmation checkpoint fires by construction. An autonomous
run contributes no node id, so the scope computation classifies it
broadand the candidate frames are enumerated for confirmation — the existing safety net, reused rather than rebuilt.confirmFrames: falseopts out, for a file holding one unambiguous creative.
The status object gains
trigger(link|auto|none) andconfirmFrames, rather than duplicating every reason into anauto-*variant, plus the terminal reasonsauto-declined,auto-unavailableandtoo-large-for-auto. - The autonomous path introspects the mapped file and nothing wider. A
project or team id would crawl an organisation — that is
-
/speckit.convergeis hooked as a task-generating phase. Converge assesses the codebase against spec/plan/tasks and appends the remaining unbuilt work totasks.md, which puts it in the same class as/speckit.tasks— already hooked. Converging without design context means the unbuilt UI work is re-derived from prose alone: the appended tasks carry no Figma value at all, and/speckit.implementthen builds from those. It is also the phase most likely to run on a PR resumed later by someone else, which is exactly the scenario the analyze/implement fix above addresses.before_convergeinvokes/speckit.figma.ensure, andafter_convergeruns the same--phase tasksverification asafter_tasks: converge rewrites a document that already carries the section, and a rewrite is where a section — and the marker every later phase keys on — gets dropped. The agent instructions add one converge-specific rule: keep the existing tasks section and its marker, add the newly derived design tasks into it, never paste a second copy. -
/speckit.figma.drift— design-drift reporting after/speckit.analyze. Analyze cross-checksspec.md,plan.mdandtasks.mdagainst each other, and all three can agree perfectly while being faithful to a creative the designer has since changed. On a PR open for two weeks that is what yields an implementation faithful to an obsolete design. The newafter_analyzehook compares the FigmalastModifiedrecorded when the document was generated against the snapshotbefore_analyzejust refreshed, and reports — it never edits a document, because whether a moved creative invalidates work already done is the developer's call.--strict(orfigma.verifyStrict) makes a real drift exit non-zero for CI; being unable to check still exits 0, so the gate fires on evidence and never on its absence. -
The rendered section marker now carries the two facts drift detection needs:
<!-- speckit-figma:section phase=spec file=<key> lastModified=<ts> -->. Reading them back from the marker rather than from the rendered prose keeps the check working the first time a heading is reworded or translated. Backward compatible by construction — every existing reader greps the fixedspeckit-figma:section phase=<phase>prefix, which still matches. A snapshot with nolastModifiedrenderslastModified=unknown, which reads as "cannot compare", never as a timestamp.
-
The extension now runs on
/speckit.analyzeand/speckit.implement.extension.ymldeclared hooks forspecify,planandtasksonly, and the--prompt-hooksfallback stopped at the same three (install.sh), so on the two remaining phases the extension was entirely absent: no snapshot, no link recovery, and.figma/figma-design-rules.mdnever loaded — during the one phase that actually writes code. The hole predates 2.0.0;v1.6.0shipped the identical hook set.What that produced in the field: a developer picking up an existing PR re-ran
analyzeandimplement, had no cache at all (.figma/cache/is git-ignored, so nothing travels with a branch, and the recovery of the link from the committedspec.mdlives insideensure), and their agent improvised — a direct Figma MCP call with a node id re-extracted from the URL, which is the usual source of "the provided node ID was not found in the file". That path bypasses node-id canonicalisation, the engine resolution and its REST fallback, the design rules, and the deterministic section.before_analyzeandbefore_implementnow invoke/speckit.figma.ensure. Both phases generate no document, so nothing is pasted andmustInjectdoes not apply to them: what the hook provides there is the context — the effective ruleset (base plus the project overlay) and a current snapshot. The agent instructions say so explicitly, in the command and in the injected managed block. SpecKit has exposed these hook points since at least v0.9.5, so no minimum-version change is needed. -
Features orphaned by the 2.0.0 trigger change are now detected. Before 2.0.0 a mapped
pageToPackageMappingwas enough to trigger design context, so a spec generated by 1.6.x can carry a full design section that records no url — it reads "None — context derived from page mapping." Under 2.0.0 the link is the trigger and the recovery path parses urls out of the committedspec.md; with none to find, the run falls through tono-figma-link, under which the agent is instructed to say nothing about Figma at all.The result was the extension's only failure mode that produced no signal:
/speckit.planand/speckit.taskssilently stopped adding the design context thatspec.mdstill displays, permanently, for that feature. The 2.0.0 CHANGELOG did not cover it./speckit.figma.updatenow runsfigma-check-orphansand lists the affected features with the two ways out — paste the link of the frame each one targets into itsspec.md, or enableautoIntrospecton the target so the mapping is a legitimate trigger again. It never edits a spec: which frame a feature targeted is precisely what those specs failed to record, and guessing it is how the wrong creative gets implemented.--strictmakes it a CI gate.
2.0.0 - 2026-08-11
-
BREAKING — the helpers and templates now run from the tree SpecKit installs,
.specify/extensions/figma/, and are no longer copied into the workspace.specify extension addalready installsscripts/,templates/and the commands there; the installer copied both into.specify/scripts/and.specify/templates/on top of that, so every workspace carried two versions of the same file. The copy has no owner — SpecKit records the version of the tree, not of the duplicate — so it silently drifts, and the stale one is the one a developer reads. Everything now invokes./.specify/extensions/figma/scripts/{bash,powershell}/…, andfigma-render-sectionresolves its templates next to itself (the workspace path remains as a fallback for un-migrated installs, but no longer takes precedence: a leftover can no longer shadow the shipped template).Consequences, all of them user-visible:
specify extension addis now a prerequisite, not one of two options.install.sh/install.ps1check the tree is present and stop with the exact command to run when it is not — before writing anything, since wiring a project around helpers that are absent produces a workspace that looks installed and fails on every hook. Run them from the installed tree (./.specify/extensions/figma/install.sh), which is what/speckit.figma.updateand/speckit.figma.confignow do.- The installers delete the duplicated
figma-*helpers and section templates earlier versions left in.specify/scripts/and.specify/templates/. Only thefigma-*entries: both directories are SpecKit's and keep its own files, and an emptied directory is removed only when it is genuinely empty.
-
BREAKING — a Figma link in the feature input is now what triggers the extension.
figma-ensure-contextused to treat a valid config with a mapped, enabled target as enough: it introspected and forced the design section into everyspec.md,plan.mdandtasks.md, so a feature like "add a Redis cache on the billing endpoint" came back carrying a Figma section it had no business carrying. The mapping infigma.projects.config.jsonsays where a creative would live, not whether a feature has one — only the link answers that. With no link the run now ends at the newno-figma-linkreason: no introspection, no rendered section,mustInject: false, and theafter_*verify hooks reportnot-applicable. -
Workspaces that relied on
pageToPackageMappingalone to obtain design context without pasting a link must now paste the Figma link in the feature description, or run/speckit.figma.introspectby hand. -
BREAKING —
/speckit.figma.setupis renamed/speckit.figma.config. The command never installed anything (install.sh/install.ps1do that): it detects the topology, writesfigma.projects.config.json, and validates connectivity.configsays what it does, and matches the sibling extensionspec-kit-charter, which already exposes/speckit.charter.config. Re-runspecify extension addto register the new name; no alias is kept, because two names for one command is the confusion the rename removes. -
roleis no longer required on a target. Validation rejected a config without it, yet no helper branched on it:figma-detect-targetcopies it into its JSON output and nothing reads it back. It stays enum-validated when present — a value outside the enum is a typo, not a choice — and stays documented, because it tells a human what a target is. Existing configs are unaffected. -
Rendered sections moved to
.figma/cache/sections/<feature>/<phase>.md, from the flat.figma/cache/section.<phase>.md. Both installers drop the old flat files. Nothing needs to reference these paths by hand — the orchestrator reports them inspecSection/planSection/tasksSection— but a workspace that hardcoded them somewhere must follow. -
As a consequence,
figma-ensure-contextno longer derives an introspection scope from the config (--team/--project/--file); that path was unreachable once a link became mandatory./speckit.figma.introspectremains the way to introspect a mapped team or project.
- Figma links detected in the feature input are remembered per feature
(
.figma/cache/links/<feature>.json, already covered by the.figma/cache/gitignore entry), so the link is pasted once at/speckit.specifyand/speckit.plan//speckit.tasksinherit it. Scoping is per feature so the next, design-less feature never inherits the previous one's link. The feature identity follows SpecKit's own resolution:SPECIFY_FEATURE, then.specify/feature.json, then the git branch. - When that per-feature memory is absent, the link is recovered from the
committed
spec.md..figma/cache/is git-ignored, so the memory does not travel with the branch: a fresh clone, a CI job or a teammate who just pulled reached/speckit.planwith no link and fell through tono-figma-link— under which the agent is told to add nothing about Figma, soplan.mdsilently lost the design sectionspec.mdcarries. The recovery is gated on thespeckit-figma:section phase=specmarker: afigma.comURL merely mentioned in the prose of a spec is not a design section and must not become a trigger. The document must also be one the current feature positively owns (identified-only): with nothing identifying the feature, "the only spec around" belongs to another one, and inheriting its creative would re-create the very regression this release removes. A recovered link re-warms the cache. - Prototype links keep their flow starting point. A
/proto/URL names two frames —node-id, whatever the designer was viewing when they copied the link, andstarting-point-node-id, the entry point of the parcours — and only the first was introspected. Both are now deep-fetched (same batched request, so no extra API cost), which also pins a prototype link whosenode-idis missing instead of degrading it to a broad link. Parsed links carry a newstartNodeIdfield. - The
no-figma-linkoutcome is now surfaced conversationally, without touching the document. Nothing distinguishes a front-end feature whose author simply forgot to paste the link from a back-end one that legitimately has none, and the document is deliberately silent — so a forgotten link produced a spec with no design context and no signal at all, throughplan.mdandtasks.mdtoo. The console line now names the remedy, and the agent instructions separate the two surfaces: nothing in the generated document, one plain sentence in the chat reply. It stays a statement, not a question: the agent still never asks for a link, blocks, or goes looking for one with an MCP tool. - Snapshots are cached per Figma file under
.figma/cache/snapshots/, on top of the singlecontext-snapshot.jsonslot. That slot is the snapshot of the current run — the well-known path every command prompt hands to the agent — and one slot is enough to publish a snapshot but not to cache one: two features targeting different Figma files evicted each other, so thefreshpath never hit and every phase re-paid a full file fetch plus a nodes fetch for a snapshot that had been valid minutes earlier. A run whose link is already covered by a stored snapshot now restores it instead of re-introspecting. - docs/ARCHITECTURE.md maps the subsystems with Mermaid diagrams: the decision flow and every skip reason, link resolution and its guards, the introspection pipeline, engine selection, credential resolution, the section lifecycle, and which parts of the config are executable versus written for human readers. Installed into workspaces alongside the other guides.
- The README now states that
figma.contextSource: "mcp"does not replace the PAT. The deterministic introspection always goes through the REST API, whatever the configured engine; MCP improves how the agent renders the design, not how the snapshot is collected. A local Dev Mode server alone, with no PAT, fails with"reason": "introspect-failed"and"code": "AUTH". - The schema now says what
pageToPackageMappingis: guidance in the/speckit.figma.introspectprompt, not a mapping any helper parses. Same forrole. - Cache housekeeping.
.figma/cache/only ever grew: alinks/<key>.jsonand asections/<key>/per branch that ever ran a phase, asnapshots/<fileId>.jsonper Figma file ever linked. Disk was not the problem — key reuse was: a key derives from a branch name, so a new feature on a recycled name inherited the remembered links of whatever used the name before it, and came back carrying a design section for someone else's mockup. Every real (non-dry) run now sweeps the cache at most once a day, on an ownership-first policy: an entry survives as long asspecs/<key>/exists — the signal is committed, so it outlives the branch — and is collected only when it is both orphaned and untouched forFIGMA_CACHE_RETENTION_DAYS(7). Stored snapshots have no owner to consult and go on age alone, never below the freshness window a caller configured. The feature of the run doing the sweep is exempt unconditionally, and a live feature's renders are never collected —figma-verify-sectionreads "Figma applied to this run" from their existence, so collecting them would turn a--strictgate fail-open.FIGMA_CACHE_GC=offdisables the sweep,=forceignores the daily throttle. figma_gc_cache/figma_gc_key_is_live(bash) andInvoke-FigmaCacheGc/Test-FigmaGcKeyIsLive(PowerShell).figma_snapshot_store_path(bash) /Get-FigmaSnapshotStorePath(PowerShell).figma_feature_key/figma_feature_links_path/figma_resolve_phase_doc(bash) andGet-FigmaFeatureKey/Get-FigmaFeatureLinksPath/Get-FigmaPhaseDoc(PowerShell).figma-verify-sectionnow shares the document resolver instead of carrying its own copy, and the resolver honours the feature identity (SPECIFY_FEATURE,.specify/feature.json) before falling back to the branch.
- A design-less feature could make a
--strictCI gate pass for a document genuinely missing its design section.figma-verify-sectiondecides "Figma applied to this run" from the existence of the rendered section, while resolving a per-feature document — but the section lived in a single global slot. Running a feature without a mockup deleted the renders of a feature with one, whoseafter_*hook then reportednot-applicable: fail-open, precisely what the gate exists to prevent. Sections are now scoped per feature, resolved through the same feature identity as the remembered links, soensureandverifyalways agree and a wipe only ever touches the current feature. - A Windows PAT stored in a default PowerShell SecretStore vault was reported
as missing. Such a vault is in password mode: the first
Get-Secretof a session opens an interactive prompt, which an agent hook can never answer. The token loaders discarded the command's stderr (2>$null/2>/dev/null) and fell through to "FIGMA_PATnot found", sending the user back to re-storing a PAT that was already stored correctly. Both loaders now capture the command's own error and print it with the warning, and a SecretStore lookup that fails additionally names the remedy —Set-SecretStoreConfiguration -Authentication None -Interaction None -Confirm:$false, which keeps the secrets encrypted at rest under the Windows user profile (DPAPI) — reporting the vault's observedAuthentication/Interactionwhen it can be read, and staying silent when the vault is already in no-password mode. The bash hint also covers Git Bash/WSL, whereGet-Secretis a cmdlet the tokenized exec cannot run at all without apwsh -NoProfile -NonInteractive -Commandwrapper. The one-timeSet-SecretStoreConfigurationstep is now part of the documented Windows setup (docs/CREDENTIALS.md, README, both installers,/speckit.figma.config, the README block template). - The PowerShell port accepted any remembered-links file that parsed, including a
JSON object root, where bash requires an array. A hand-edited
.figma/cache/links/<feature>.jsonholding a single object instead of a one-element array was honoured on Windows and ignored everywhere else. The check now reads the JSON root off the text, becauseConvertFrom-Jsonunrolls a one-element array into a bare object and the deserialized shape cannot tell the two apart.
1.7.0 - 2026-08-10
- Node ids are now canonicalized at a single chokepoint
(
figma_normalize_node_id/ConvertTo-FigmaNodeId), so the URL form Figma puts in deep links can no longer reach a server as-is. Previouslyfigma-parse-linksconverted only the first separator and required the id to start with a digit, which left nested-instance links (node-id=I123-456%3B789-012) unresolved and could forward a partially normalized id — both surface as "The provided node ID was not found in the file". The extractor now takes the wholenode-idvalue (the&t=…tracking suffix can no longer leak in), normalizes every separator, and reports an unrecognized value asnull(broad link → the agent asks which frame) instead of forwarding a bogus id. figma-introspect --nodevalidates and canonicalizes its input before any network call:12-345is accepted and queried as12:345, and a malformed value fails with an explicit error instead of an empty node set.- A missing
jqno longer breaks the auto-context hook's contract. It used to abort with a bare "'jq' is required but not installed" before emitting any status object, leaving the agent with nothing and pushing it to improvise — typically direct Figma MCP calls with a hand-extracted node id, the very failure above.figma-ensure-context.shnow answers with a jq-free{"ran":false,"reason":"missing-dependency","dependency":"jq",…}on stdout and exits 0, and everyfigma_requirefailure prints an install path that works withoutsudoor a writable Homebrew Cellar.
- MCP node-id contract in the command prompts (
/speckit.figma.introspectsection 1b-bis,/speckit.figma.ensuresection 2). Passing ids to MCP tools was previously left to the model's own judgement, which made the step model-dependent: agents must now reuse thefileId/nodeIdpair produced byparseverbatim, never re-derive an id from a URL, and treat a nullnodeIdas a broad link. - A
missing-dependencydegraded-mode protocol in/speckit.figma.ensure(section 4) and/speckit.figma.introspect(section 1b-bis): when the helpers cannot run, the agent must apply the node-id normalization steps literally (cut at&/#, decode%3A/%3B, replace every-, validate the shape, pair with the file key of the same URL) and relay the install instructions instead of silently staying degraded. - MCP installation instructions for Claude Code and VS Code in the
managed README block written by the installer, and a dedicated section in
docs/INSTALL.mdcovering the hosted server, the local Dev Mode server, and a troubleshooting table for "The provided node ID was not found in the file" (including the fact that MCP authenticates separately from the PAT). - A
jqprerequisite callout — with the admin-free static-binary install — indocs/INSTALL.md, the README requirements and the managed README block.
1.6.0 - 2026-07-07
.extensionignoresospecify extension addinstalls a clean copy: the test suites (bats/Pester), CI configuration and repo-only dotfiles are excluded from the installed extension (#9).CHANGELOG.md(this file) and thehomepagefield inextension.yml, aligning the extension with the Spec Kit extension catalog publishing requirements.
extension.yml: the manifestdescriptionwas shortened to meet the catalog limit (under 100 characters); the full feature description lives in the README.- README: the recommended
specify extension add --fromURL now points to the latest tagged release archive instead of themainbranch, so installs are reproducible and match the published catalog entry.
1.5.0 - 2026-07-03
- Updates are standardized as "fetch from the official repository": the
/speckit.figma.updateflow performs a fresh shallow clone of the official repo (#7). - Added an "Updating" section to the managed README block pointing to
/speckit.figma.updateand the official repository. - Install/update documentation revised accordingly.
1.4.0 - 2026-07-02
- Windows support: PowerShell 7+ ports of every bash helper
(
scripts/powershell/, 9 scripts) with the same flags, JSON output and exit codes — commands, hooks and CI gates behave identically on macOS, Linux and Windows (#6). Windows needs onlypwshandgit(built-in HTTP/JSON: no curl, no jq). - New
install.ps1: full port ofinstall.sh(managed README/hook blocks, version-coherence check, command-drift detection). - New Pester suite (
tests/powershell/, 108 tests) plus CI jobs onwindows-latestandubuntu-latest, and PSScriptAnalyzer lint.
- Both installers now copy both script families into the workspace
(
.specify/scripts/bash/and.specify/scripts/powershell/), so a mixed macOS/Linux/Windows team shares one committed setup. extension.ymltool requirements:gitstays required;bash/curl/jqbecome POSIX-only;pwshis the Windows alternative.
1.3.0 - 2026-07-02
install.shnow copies the user-facing guides (CREDENTIALS.md,INSTALL.md,MONOREPO.md) into the workspace at.figma/docs/, refreshed on every update so they match the installed version (#5).- Managed figma section appended to the workspace
README.md(created if missing): extension version + layout mode, the read-only Figma PAT setup and links to the local guides. Refreshed in place on re-runs; opt out with--no-readme.
1.2.0 - 2026-07-02
- Persistent user overlay
.figma/figma-design-rules.custom.md: per-project design-rule customizations that survive updates, with local-wins precedence over the extension-owned base (#4). - Graceful no-Design-System support: component resolution collapses to reuse → app/lib and token gaps are not raised.
- Snapshot/render state moved under a dedicated cache directory
(
.figma/cache/); the design-rules concept renamed from "memory" to constitution (#3). - The shipped base constitution is now universal: mobile-first, Storybook and the CI token-gap trigger moved to the overlay as opt-in defaults.
1.1.0 - 2026-07-02
figma-render-section.sh: renders the spec/plan/tasks design sections with every deterministic placeholder pre-filled, so the agent integrates the section regardless of model (#2).before_planhook andplan-figma-section.template.md.- Post-generation verification gate (
figma-verify-section.sh,/speckit.figma.verify,after_*hooks) with--strictCI mode. - Broad Figma links (file/page-level) detected as
linkScope: "broad"withcandidateFrameslisted for selection. - First-class idempotent update flow (
/speckit.figma.update). - Proxy-vs-auth failure diagnostics and native MCP recommendations for Claude Code / VS Code.
- Documented that project/team introspection requires the
projects:readPAT scope, with a scope matrix indocs/CREDENTIALS.mdand an actionable403/404hint (figma_scope_hint).
1.0.0 - 2026-06-17
- Initial release: agent-agnostic SpecKit extension grounding spec/plan/tasks generation in Figma design context (#1).
- Portable REST engine (curl + jq) with optional MCP engine and automatic REST fallback.
- Single-repo, mono-repo and multi-repo layouts driven by
figma.projects.config.json. - 3-level component resolution (reuse → create-in-DS → create-in-app) with a purely presentational Design System.
- bats test suite and shellcheck lint, run in CI.