Changelog

​

uSpec V2.3

​

Typed componentProperties snapshot (Figma plugin 2.4.0)

• Phase E captures componentProperties on every walked INSTANCE via the new snapshotComponentProperties helper in figma-plugin/src/safe.ts. The snapshot mirrors Figma’s InstanceNode.componentProperties API exactly — every entry carries { type, value } with type typed to BOOLEAN | INSTANCE_SWAP | TEXT | VARIANT | SLOT — and strips Figma’s #… clean-key suffix from each property name
• Phase F′ (childComposition.ts) forwards the snapshot into every _childComposition.children[*] entry, and the plugin UI round-trips it back into the sandbox so the extract merge can attach it to slot-origin entries that bypass the first-guess builder. null for non-INSTANCE entries (FRAMEs, vectors, layout wrappers) and for slot-preferred entries (which describe a referenced component, not a placed instance — read propertyDefinitions.slots[].preferredInstances[] for those defaults)
• booleanOverrides is now legacy. The field is still emitted on every entry — it’s used by the first-guess fingerprinting that groups identical sub-component placements — but it’s now a booleans-only projection over the typed snapshot instead of an independent read. Slot-default-child entries that previously carried an empty booleanOverrides now carry the projected booleans correctly
• The new field is documented in figma-plugin/docs/base-json-schema.md and the plugin’s post-change checklist

​

SLOT-binding bug fix (Figma plugin 2.4.0)

• SLOT nodes are now matched to their declared slot property via the new getSlotPropName helper, which prefers the authoritative componentPropertyReferences.mainComponent binding (per Figma’s SlotNode docs) and falls back to the SLOT node’s own name when that binding is absent — the common case in real files, where SLOTs typically only carry the visible binding to a separate BOOLEAN prop
• This replaces a buggy Object.values(cpRefs)[0] lookup in phaseA.ts and code.ts that was picking up the visible binding (e.g., “show leading slot”) instead of the slot binding (e.g., “leading slot”), causing every later lookup-by-slot-prop-name to miss and silently dropping default-child instances from the classification UI
• The plugin now also logs a soft console.warn when a declared slot property has no matching SLOT node in the default variant — surfaces designer-side renames or genuinely empty slots so the gap is visible

​

Renderer rewrite for Referenced components (uspec-skills 0.2.11)

• references/component-md/agent-component-md-instruction.md introduces three small helpers shared by the Composition bullet rules and the API “Referenced components” #### block:
  • displayName(child) prefers parentSetName over the variant-identifier mainComponentName. When a referenced child is a variant of a COMPONENT_SET, Figma’s mainComponentName is the variant identifier ("layout=icon-only, size=small, color=default") — useful as a configuration but useless as a component name. parentSetName is the human-readable set name ("action button")
  • slug(child) derives the spec filename from displayName(child) instead of the raw main-component name, so multi-variant references resolve to the right ./{slug}.md
  • slotSuffix(child) appends " (via slot **{slotName}**)" when a referenced child lives inside a SLOT, so the engineer can locate it in the parent’s anatomy without cross-referencing the API’s slot table
• The “Referenced components” override table now reads child.componentProperties exclusively. One row per entry in the typed dict, with per-type value formatting:
  • BOOLEAN → true / false
  • INSTANCE_SWAP → (instance \`)`
  • TEXT → the literal string in backticks
  • VARIANT → the bare option, with "Variant axis on the placed instance." in the Notes column
• The legacy booleanOverrides field remains on every entry for backward compatibility with the first-guess fingerprinting, but is no longer the source of truth for the rendered table. subCompVariantAxes is also explicitly demoted from the table — it lists what axes the child exposes, not what the parent’s placement chose, and belongs in the referenced child’s own spec
• Slot context is folded into the lead paragraph as a participle clause (“…as the default fill of the slot”) so it shows up exactly where the engineer needs it
• Decorative-children rollup is now scoped to top-level entries only — slot-origin entries never appear at the top level and are not part of that count

​

Documentation

• implementation.md now documents the two new safe.ts exports (snapshotComponentProperties, getSlotPropName), the SLOT-binding bug fix that motivated the latter, and the Phase F′ → renderer flow for the typed componentProperties snapshot
• figma-plugin/docs/base-json-schema.md documents the new componentProperties field on _childComposition.children[], demotes booleanOverrides to a backward-compat projection, and adds the field to the post-change checklist

​

uSpec V2.2

​

Render-meta appendix in Component Markdown

• The component-md template gains a fenced JSON block delimited by <!-- render-meta:start v=1 --> / <!-- render-meta:end --> carrying machine-readable component metadata: schemaVersion, extractedAt, sourceHash, fileKey, nodeId, component, variantAxes / variantAxesDefaults, propertyDefs, booleanDefs, subComponents, slotContents, sectionTargets, groupTargets
• Downstream create-* skills (structure, color, anatomy, property, …) read this block to resolve sections, row-groups, and boolean-gated layers back to live Figma layers — no more fuzzy name matching against layoutTree and no need to re-extract through MCP
• schemaVersion is pinned at "1.0" for V2.2; future breaking changes will bump it. sourceHash is a SHA-256 of the underlying _base.json so consumers can detect drift between the .md and the extraction it was rendered from
• The block is mechanical pass-through of _base.json and the structure cache — no interpretation, no synthesis. Two create-component-md runs against the same _base.json produce byte-identical render-meta

​

Layer identity stamped on structure output

• extract-structure’s new R6 rule populates section._anchor ({ layerName, layerId }) on every section and row._layerName / row._layerId on every group-header row, reading directly from _base.json.variants[<default>].layoutTree
• Composition sections anchor to the variant root with layerName: "__root__"; sub-component sections anchor to the in-context INSTANCE node (NOT the canonical subCompSetId, which is already covered by render-meta subComponents[]); slot-content sections anchor to the slot’s host frame; zone-specific sections anchor to the named FRAME
• Group-header rows (any row where isSubProperty !== true AND spec is a zone descriptor, not a property family) carry the literal Figma layer name and node id. Layers present only in revealedByVariantName[*] (e.g., a clear button parked under state=active) emit _layerId: null with an explanatory notes entry — the row is still present, just unpinned
• The create-component-md orchestrator now reads these fields directly into render-meta. A legacy fallback (name-walk against layoutTree) covers caches produced before this release; re-running extract-structure is recommended to regenerate the cache with the new fields

​

borderWidth + borderAlign row pair

• Whenever a borderWidth row is queued (gate: strokePaintToken != null), a sibling borderAlign row is queued from dimensions.strokeAlign.display (inside / outside / center). The two rows share the same gate — emit both, or neither
• The coverage matrix (_extractionArtifacts.coverageMatrix) accepts borderAlign as a first-class family alongside borderWidth, with identical R4/R5 detection rules
• Legacy fallback: when dimensions.strokeAlign is absent from a _base.json produced by a pre-2.3.0 plugin build, borderAlign emits as "—" with provenance: "not-measured" and generalNotes surfaces a single line recommending re-extraction. No row is silently dropped

​

Figma plugin 2.3.0 (uspec-extract)

• Boolean-gated layer fallback (Phase A). Boolean property → gated layer resolution now walks componentPropertyReferences.visible instead of relying on the default variant’s componentProperties keys. When the gated layer is absent from the default variant (e.g., a “clear” button that only appears when input is active), the resolver falls back to scanning every sibling variant in the COMPONENT_SET. First match wins; the resulting associatedLayerId is canonical and downstream-consumable
• strokeAlign capture (Phase E). extractDims() now emits strokeAlign as { value, token: null, display } where value is the raw Figma enum ("INSIDE" / "OUTSIDE" / "CENTER") and display is the lower-cased prose form. Present on variants[].dimensions, variants[].treeHierarchical[*].dimensions, and every subComponentVariantWalks entry. Not on variants[].revealedTree[*].dimensions — Phase G uses a minimal dim() extractor focused on topology; dimensional ground truth always comes from the baseline treeHierarchical
• Node ids on every walk entry. treeHierarchical, layoutTree, treeFlat, colorWalk, revealedTree, revealedColorWalk, and Phase I’s measureHierarchical all carry the Figma node id (or nodeId for color entries) of the source layer. Downstream consumers resolve walk entries back to live layers without name- or path-based search
• Rebuild locally to pick up the changes: cd figma-plugin && npm install && npm run build, then re-import the manifest in Figma Desktop. The plugin doesn’t ship via npm — it’s built per-machine

​

borderWidth gate fix and authoring discipline

• borderWidth rows now require strokeWeight.value > 0. The extractor emits strokeWeight: { value: 0 } for nodes that have the property set but no paint in node.strokes; without this gate the agent emitted a phantom borderWidth: 0 row even though no border is painted on the component
• The structure rendering rules now forbid Figma node ids and TODO: confirm with Figma stubs in Notes columns. Notes is engineer-facing implementation context — when a value cannot be confirmed, skip the row or surface the gap in generalNotes rather than leak extraction-time artifacts into the rendered spec
• The Mode A / Mode B split, per-group annotation resolver, and cross-variant 4d/4e drivers added on top of V2.1.4’s 7d2e7f4 baseline are reverted — they made the workflow brittle without improving output. create-structure is back on the unified rootOnly / fullTree annotation model with cleaner output

​

Housekeeping

• maintaining.md updated for npm’s current web-based 2FA flow — npm publish now opens a browser tab for approval and no longer requires --otp=…. The authenticator-app fallback is documented for accounts not on web-based 2FA
• New root-level .npmrc mirrors packages/cli/.npmrc and pins the registry to public npm at the repo level. The layered registry safety (publish config + .npmrc + prepublish guard) still aborts mis-pointed publishes with a clear error
• utils/README.md removed (utils/ is no longer a meaningful directory in the repo)
• README.md and implementation.md prose tightened — the canvas-measurements paragraph now documents the rootOnly vs fullTree annotation policy explicitly and the new { success, plannedColumns } return semantics

​

uSpec V2.1.4

​

.md-authoritative mode (Structure)

• skills/create-structure/SKILL.md adds Step 0 — Detect Input Mode. Mode A is description-only (today’s behavior). Mode B reads components/<name>.md in full and persists it as MD_SPEC before any extraction runs
• Step 4 (visual context, enhanced extraction, cross-variant comparison, non-dimensional axis diff) still runs in Mode B, but its output is demoted to a node-ID resolver and drift detector. Extraction values that disagree with the .md are logged in generalNotes and the .md value wins
• Step 6 in Mode B is reduced to (1) mapping each .md row to extraction nodes for annotation rendering, (2) reconciling each .md row against the corresponding extraction value, (3) skipping the cross-section pattern recognition pass (create-component-md already did it)
• Every emitted row now carries a required provenance field: "md" (value came from the .md), "measured" (.md was silent, value came from extraction), "user-rule" (value came from a user adjustment rule), or "inferred" (with an accompanying note explaining what was inferred from what). Rows without a defensible provenance are not emitted
• When both a description and an authoritative .md are provided, the .md wins for properties it documents and the description applies only to anything the .md is silent on

​

Reasoning discipline (Structure)

• references/structure/agent-structure-instruction.md adds a Reasoning Discipline section that applies at every step — extraction interpretation through rendering. Five rules: (1) the .md is the source of truth when provided, (2) every row needs provenance, (3) no confabulation — skip rows or surface gaps in generalNotes rather than fill in defaults, (4) screenshots verify layout intent only, not paints/strokes/spacings/radii/tokens, (5) strokeWeight alone is not evidence of a border
• The Conflicts table grows a new top row covering authoritative .md precedence, and the existing “Figma contradicts description” row is qualified to “no .md provided”
• The Common Mistakes section adds matching entries: hand-rolling canvas measurements, hand-curating the annotation plan, treating strokeWeight as evidence of a border, citing screenshots for paint or border decisions
• The Do NOT list adds: overriding an authoritative .md value with anything inferred from extraction or screenshots, emitting borderWidth when strokePaintToken == null, citing a screenshot as evidence for paints/strokes/spacing/radii/tokens, inventing values to fill rows

​

strokeWeight no longer implies a border (Structure)

• The Stroke weight reading reference in references/structure/agent-structure-instruction.md is rewritten around a new strokePaintToken signal co-emitted by the extractor. A frame can carry strokeWeight: 1 with strokes: [] — no border is painted, and a phantom borderWidth row should never be emitted from such a node
• New emission rule: emit a borderWidth row only when strokePaintToken != null. The Inspect Reference table’s Stroke width row is updated to match
• The collapsed dimensional schema description in ## Dimensional Data clarifies that strokeWeight is only authoritative as evidence of a border when paired with a non-null strokePaintToken

​

use_figma / figma_execute script escaping (architecture)

• implementation.md adds a new “Authoring code strings for use_figma / figma_execute” subsection under Figma MCP Tools. Both providers serialize the code argument through JSON before the Figma sandbox runs it, so \' inside a '...' JS string is a recurring source of SyntaxError after re-escape
• Rule: when authoring note text, descriptions, or any content with apostrophes (clear-button copy like "Visible when value isn't empty", contracted English in design-intent notes), wrap the JS string in "..." (double quotes) or use template literals (backticks). Never reach for \' inside a '...' string. This applies to every skill that ships note-bearing rows through __ROWS_JSON__ or its equivalents

​

Figma plugin manifest id

• figma-plugin/manifest.json now declares its registration id: "1635184425006534227". This is the plugin’s permanent identity in the Figma plugin registry — it does not change anything about how the plugin runs locally or what _base.json it produces, but it stabilises the manifest for future plugin distribution work

​

Scope

• No changes to extraction shape, table contents, sub-component walks, slot handling, or canvas measurement overlay behavior beyond the borderWidth-gating rule above
• Already-rendered Figma structure specs are unaffected — the new mode and the new emission rule only change future create-structure runs

​

uspec-skills 0.2.8

​

What you might notice after updating

• Running npx uspec-skills update may delete stale files in your local references/ directory that were never part of the current source tree (e.g., files like references/_shared/mcp-adapter.md or references/structure/scripts/*.js that were removed from the source long ago but kept resurrecting). This is the cleanup catching up
• No skill or spec behavior changes. This is a packaging hygiene fix only

​

uSpec V2.1.3

​

Why the walk could throw (Structure)

• Step 4b extractDimensions and Step 4d measureNode recurse into every child via extractChildren / measureChildren. Children include heterogeneous node types — TEXT, VECTOR, GROUP — that do not support auto-layout properties
• The Figma plugin API throws synchronously when you read itemSpacing (or other layout-only properties) on a node that doesn’t support them. The previous guard node[p] !== undefined && node[p] !== figma.mixed ran the access first, so the throw fired before the comparison
• Step 4e already used the correct defensive pattern (per-access try/catch plus an isContainer = 'layoutMode' in node gate); Steps 4b and 4d now match it

​

Defensive read pattern (Structure)

• Every property read in Steps 4b and 4d is now wrapped in try { ... } catch {}, mirroring the sg(node, prop) accessor in figma-plugin/src/safe.ts
• Layout-only property groups (padding, itemSpacing, counterAxisSpacing, layoutMode, primary/counter axis aligns, layoutSizing*, clipsContent) are gated on isContainer = 'layoutMode' in node so leaf nodes skip them entirely instead of throwing
• The collapsed dimensional schema (padding, cornerRadius, strokeWeight, typography) is unchanged — Steps 5, 6, and 11 read the same shape they always did

​

Documentation (uspec-skills 0.2.7)

• skills/create-structure/SKILL.md adds a maintainer note above the Step 4b script explaining the throw-on-leaf hazard and the try/catch + isContainer pattern, so future script edits stay safe by default

​

Scope

• No changes to extraction shape, plan-building, table contents, sub-component walks, or canvas measurement overlays
• Already-rendered Figma structure specs are unaffected — this fix unblocks future runs on components whose default variant has TEXT children at the root or inside auto-layout containers

​

uSpec V2.1.2

​

Why the labels could disagree with the table (Structure)

• Hardcoded padding rows draw a measurement line whose pixel length is what Figma renders as the label. Until V2.1.2 the line always anchored to the first or last visible child, so on a horizontal capsule with counterAxisAlignItems: CENTER and HUG-sized children the line measured the centering offset rather than the autolayout padding
• Token-bound padding rows were unaffected — freeText carries the token name regardless of geometry — and gap / itemSpacing rows were unaffected because consecutive children sit edge-to-edge with the gap by definition. Only hardcoded counter-axis padding rows misread

​

Padding anchor rule (Structure)

• The Step 11c annotation script now picks the child whose edge sits on the container’s inner-content edge for that side (within a 0.5-px epsilon of paddingTop / paddingBottom / paddingLeft / paddingRight) and draws the line against that child. Figma’s default numeric label then matches the autolayout value the table documents
• When no child aligns to that edge, the line falls back to the first/last visible child but carries a freeText override of the autolayout value so the label still matches the table
• Implemented inline as a new findEdgeAnchor helper above annotate; no per-row configuration is required

​

Documentation (uspec-skills 0.2.6)

• references/structure/agent-structure-instruction.md splits the freeText policy bullet into “hardcoded padding row” (anchor + fallback) vs “hardcoded gap/itemSpacing row” (default label) so the contract the agent reads matches what the SKILL implements
• implementation.md updates the “Canvas measurements (Structure)” architecture summary to describe the anchor + freeText-fallback policy

​

Scope

• No changes to extraction, plan-building, table contents, or the markdown spec
• Already-rendered Figma structure specs keep their old labels until they are explicitly re-annotated; the fix changes only future runs and any explicit re-annotation pass

​

uspec-skills 0.2.5

​

Native canvas measurements (Structure)

• Step 11c emits page.addMeasurement(...) for the allow-listed auto-layout properties documented in the section table: paddingTop / paddingRight / paddingBottom / paddingLeft, itemSpacing, minWidth / maxWidth, and minHeight / maxHeight. Other properties (corner radius, typography, color) remain table-only by design
• Token-bound rows pass the token name as freeText so the measurement label reads as the token, not just the resolved pixel value. Hardcoded rows render Figma’s default numeric label. Min/max constraints render with a "min N" / "max N" prefix
• Per-instance idempotency is provided by getMeasurementsForNode(...) + deleteMeasurement(...) before each annotation pass, so re-running a section never duplicates overlays
• Both figma-console (figma_execute) and figma-mcp (use_figma) execute the identical script — no MCP-specific branching

​

Preview fidelity (Structure)

• Slot content previews now nest the preferred component instance into the actual SLOT node inside the preview, so the slot region renders with real content instead of an empty placeholder. If appendChild fails (for example in a read-only context), the preview falls back to a 0.6-opacity ghost overlay positioned at the slot bbox
• Recursive boolean enabling reaches every nested instance in the preview except inside boolean-toggled sections, so optional children documented in the table actually appear in the rendered preview
• Step 12 verification adds a measurementCount / plannedColumns contract check on the value returned by Step 11c. Measurement overlays are a canvas layer that does not appear in figma_take_screenshot / get_screenshot output, so visual screenshot review is no longer the source of truth for measurement coverage

​

Documentation

• references/structure/agent-structure-instruction.md adds a Canvas Measurements subsection covering the allow-list, freeText semantics, annotation scope, and the screenshot caveat
• implementation.md documents the render-time slot nesting and canvas measurement architecture parallel to the existing marker positioning notes

​

uSpec V2.1.1

​

Recommendation update

• references/api/api-library.md now recommends hovered alongside pressed and focused. The recommendation table also explicitly documents that earlier docs and many existing Figma libraries use hover, and that both forms are recognized by the extractor.
• All instruction files (agent-api, agent-color, agent-structure, agent-anatomy) and skill prose updated to use Hovered / hovered in state listings, JSON examples, and worked examples.
• Mintlify spec pages, Getting started examples, and Troubleshooting prompt suggestions updated to match.

​

Backwards compatibility (figma-plugin 2.1.1)

• The stateKeywords matcher in figma-plugin/src/phaseF.ts and skills/create-color/SKILL.md accepts both hover and hovered as state-axis option names, so designers who keep the legacy name continue to get correct axis classification.
• Real design-token identifiers (hoverOverlayAlpha, interactivePrimaryHover, etc.) are unchanged — these are platform variable names, not state labels.
• Generated specs continue to render whichever form the source Figma file uses; output is truthful pass-through, not a silent rewrite.

​

uSpec V2.1

​

Layout-wrapper descent (Figma plugin 2.1.0)

• Designers commonly wrap a component’s real sub-components in a single auto-layout FRAME for clipping, scroll, padding, or grouping (for example, a Button group’s group wrapper for the overflow=scroll variant). The plugin now descends through these wrappers so the classification UI surfaces the actual sub-components instead of the wrapper
• Each wrapper is recorded as an explicit decorative entry in _childComposition.children[] with topLevelInstanceId: "wrapper:<depth>" and classificationEvidence: ["layout-wrapper"], so layout chrome remains visible to downstream consumers
• idx:N in topLevelInstanceId now indexes into the effective container (post wrapper descent), not the variant root. Phase I and treeHierarchical are unaffected

​

Sub-component placement dedup (Figma plugin 2.1.0)

• Repeated placements of the same sub-component (for example, six Selection Button instances inside a Button group) now collapse to one _childComposition entry instead of N. The designer classifies once; multiplicity is recorded in three new fields:
  • placementCount — number of sibling placements that share the entry’s identity
  • placementIndices — original positions in the effective container’s children
  • placementsVary — true when at least two placements differ in main component or boolean overrides, signalling a heterogeneous array
• The plugin UI surfaces a × N badge on grouped rows and a varies in state tag when placementsVary is true, so the designer can spot heterogeneous arrays at a glance
• Equivalence fingerprint covers mainComponentName (which encodes variant choice for component-set members) and booleanOverrides — instance-swap and text-override differences are intentionally not in the fingerprint and remain visible in treeHierarchical

​

create-component-md Step 4.5 fix (uspec-skills 0.2.3)

• The post-extract review previously flagged any _childComposition entry without user-selected evidence as malformed. The new wrapper FRAME entries legitimately carry ["layout-wrapper"] evidence, so the check is now scoped to nodeType === "INSTANCE" — the only entries the plugin UI asks the designer to confirm
• Prevents a spurious “the plugin UI did not reach the designer’s confirmation step” warning and a redundant override pass on every plugin run that contains a layout wrapper
• Run npx uspec-skills update to pick up the fix

​

uspec-skills 0.2.2

​

uSpec V2.0

​

New: uspec-skills install CLI (0.2.0)

• Run npx uspec-skills init from any project root. The CLI prompts for your agent host (Cursor, Claude Code, or Codex) and your Figma MCP provider, installs every skill into the matching platform directory (.cursor/skills/, .claude/skills/, or .agents/skills/), copies references into ./references/, and writes uspecs.config.json
• npx uspec-skills install --platform <cursor|claude-code|codex> reinstalls or repairs skills non-interactively
• npx uspec-skills update re-renders skills against the current package version
• npx uspec-skills doctor validates your install and reports missing skills, missing references, or broken cross-references
• init bootstraps a fresh uSpec project into the current directory when no project root marker (.git/, package.json, or uspecs.config.json) is found above it, so the documented “create a new folder, then run init” walkthrough works from an empty directory. A one-line note (bootstrapping a new uSpec project here.) is printed when this happens
• uspec-skills install points you at npx uspec-skills init when run from a directory with no project root, instead of failing with a generic message
• All CLI error and log prefixes consistently say uspec-skills (the legacy uspec shorthand has been removed)
• The previous flow (cloning the repo and running utils/sync-skills.sh) is no longer required. Existing users can keep their clone, but new setups should use npx uspec-skills init from their own project root
• uspecs.config.json now records the chosen platform and MCP provider so firstrun reads them from disk instead of asking again

​

New skill: create-component-md

• Orchestrator skill that turns a plugin-produced _base.json into a single components/{componentSlug}.md file
• Runs four interpretation specialists: extract-api (serial, produces the shared property dictionary), then extract-structure, extract-color, and extract-voice in a parallel batch
• Deterministic reconciliation gate catches typed disagreements between specialists (conflicting child classifications, mismatched axes, missing states) and serially re-dispatches only the specialist that owns the mismatch
• Integrity gate validates cache-file shapes, axis consistency, and structure coverage matrix before rendering the Markdown
• Output sections: Overview, API, Structure, Color, Voice / Screen reader, Provenance. Everything needed to implement the component from scratch without opening Figma
• Cost envelope: 50k–200k tokens per run. Recommended model: Opus 4.7 High or above
• Full guide →

​

uSpec Extract Figma plugin

• New Figma plugin that captures a component’s complete extractable state in one pass
• Walks every variant (no default-variant sampling), resolves library-linked variables with name, codeSyntax, alias chains, and remote collection metadata, and captures inline font properties alongside text style IDs
• Phase I: sub-component variant walks. Constitutive sub-components are measured across their own variant axes, not only the configuration the parent embeds, so a Button inside a Text Field is specified at every size and density
• Designer-in-the-loop classification checklist: confirm or flip whether each top-level child is constitutive, referenced, or decorative before extraction
• Runs entirely inside the Figma plugin sandbox with no network access. Nothing is stored, nothing leaves your machine. To build locally, clone the uSpec repo, run npm install && npm run build inside figma-plugin/, then import the manifest in Figma Desktop. See the install walkthrough
• Output is a validated _base.json (Ajv schema at figma-plugin/docs/base-json-schema.md) that becomes the sole input for create-component-md

​

Documentation

• New Component Markdown spec page covering install, usage, the four-specialist pipeline, and skill-side troubleshooting
• New Figma Extract plugin tab on the Troubleshooting page covering build steps, Node version requirements, the watch-mode dev loop, and common install failure modes
• Getting Started rewritten around the CLI flow with platform-specific tabs
• Troubleshooting updated with npx uspec-skills doctor and per-platform repair commands

​

Structure skill: coverage matrix artifact

• extract-structure now emits a _extractionArtifacts.coverageMatrix artifact listing every auto-layout frame walked, the non-zero layout properties found on it, and whether a corresponding row was emitted in the final spec
• The orchestrator’s integrity step asserts coverageMatrix.complete === true and independently recounts frames walked, so silently dropped padding or spacing is caught before rendering
• Fixes a class of bugs where inner wrapper frames with non-zero horizontalPadding or itemSpacing could be measured but not emitted

​

Dual-path architecture

• implementation.md fully rewritten to describe both rendering paths, the plugin phases (A–I), the orchestrator workflow, the .uspec-cache/ layout, and the extract-* interpretation skills
• uspecs.config.json gains extractionSource: "plugin" and reconciliation: { autoRetry: true } to control the new path
• .uspec-cache/{componentSlug}/ directory stages the plugin payload and caches each specialist’s JSON output. Useful for debugging and for re-running only part of the pipeline

​

uSpec V1.8.1

​

Recursive nested container measurement (Structure)

• measureChildren now calls itself recursively instead of using a flat loop for grandchildren — deeply nested wrapper frames (e.g., icon containers inside trailingContent) are fully measured and surfaced as __children entries in the cross-variant data
• Fixes cases where intermediate auto-layout frames with their own padding were invisible to the completeness check

​

Wrapper frame padding coverage (Structure)

• New verification procedure in the completeness judgment: for each sub-component section, walk __children entries recursively — every entry with non-zero padding is an auto-layout container that needs its own group with dedicated rows
• Catches content areas (e.g., leadingContent, trailingContent) whose children each have individual padding that was previously collapsed into a single note on the parent
• Cross-checks against enrichedTree when available for redundant validation

​

Common mistake guidance (Structure)

• New “Collapsing wrapper frame padding into notes” entry in the instruction file — documents the anti-pattern of merging per-child padding into a parent group header note instead of giving each wrapper its own group

​

uSpec V1.8.0

​

Composite style support (Color)

• New buildCompositeDetail function in the extraction script detects paint styles with 2+ visible fill layers and emits a compositeDetail object with layer stacking order, blend modes, opacities, and gradient stops
• Token resolution priority updated: paint/stroke style names (fillStyleId, strokeStyleId) now take precedence over variable bindings (boundVariables.color), matching how effect styles are already handled
• AI interpretation builds compositeChildren arrays on elements — solid layers, gradient layers with per-stop detail, and image layers — rendered as nested rows with hierarchy indicators (#hierarchy-indicator frame toggled per child row)
• Both Strategy A (simple) and Strategy B (state-consolidated) rendering scripts support composite child rows with showIndicator for middle/last-child visual connectors
• Instruction file adds composite breakdown guidance, worked examples, rendering rules, and validation checklist items

​

Exhibit planning and context axis rendering (Property)

• New Step 1 reads a dedicated instruction file (agent-property-instruction.md) containing data validation, exhibit planning, pre-render checklist, common mistakes, and do-not rules — previously inline in SKILL.md
• Step 4e now includes exhibit planning (Phase B) that produces an exhibitPlan array routing each property to the correct rendering template
• New context axis system: when a variant axis qualifies as a visual context (e.g., variant: primary/subtle), all other illustrated chapters render grouped rows per context value using new 6a-ctx and 6b-ctx templates
• New 6a-matrix template for sparse variant matrices — absolute-positioned grid with N/A placeholders for missing combinations, plus standalone chapters for both axes
• Step renumbering (1–11) with a new Step 5 audit pass that re-reads the instruction file’s pre-render checklist before rendering
• All implementation notes moved from the SKILL.md Notes section to the instruction file, reducing SKILL.md scope to pure orchestration

​

Non-dimensional axis coverage (Structure)

• New Step 4e runs a diff script measuring root and direct children across every variant axis not already covered by size/density/shape extraction
• Step 6 classifies each axis as structural (children differ → separate sections per configuration), property-variant (dimensional properties differ → state-conditional section), or visual-only (skip)
• New Step 6b runs targeted follow-up extractions for structural axes, giving each configuration complete dimensional data across all sizes
• Instruction file adds non-dimensional variant axis guidance, decision table entries, and common mistake warnings for skipped diffs and missing property-variant sections
• User-provided value adjustments now replace extracted values in existing rows with explanatory notes instead of creating duplicate rows

​

Sub-pixel precision (Structure)

• All rounding functions updated from Math.round() to a rv() helper that preserves one decimal place (Math.round(v * 10) / 10) — values like 1.5px stay 1.5 instead of rounding to 2
• Applied across both Step 4b enhanced extraction and Step 4d cross-variant comparison scripts
• Instruction file updated: “Preserve one decimal place; whole numbers stay whole”

​

Anatomy refinements

• Root variant fills/effects now fold into the container note when a container synthetic already exists, instead of always creating a separate statelayer/backplate element
• Ghost overlays for failed slot insertions deferred to after auto-layout reflow so they use final positioning
• instAbsX/instAbsY recomputed after centering to fix absolute transform drift

​

Element naming (Color)

• Fill-bearing elements now consistently use a property qualifier: “Container fill” instead of “Container”, “Background fill” instead of “Background” — removes ambiguity when the same element also has a stroke

​

uSpec V1.7.4

​

Evidence-based API reasoning

• New ownershipHints array in the extraction script collects deterministic ownership cues from root properties, child overrides, text nodes, and variable collections — each hint includes evidenceType, suggestedExposure, and a rationale
• New Step 4c requires assembling a structured ComponentEvidence object before reasoning about the API — keeping raw facts separate from semantic interpretation
• relevantVariableCollections are now extracted inline during property extraction, with component-name and generic-property matching to discover mode-controlled capabilities like density and shape
• The instruction file introduces a ComponentEvidence TypeScript interface as the required intermediate model between extraction and API generation

​

Override promotion pass

• Step 5 now includes a mandatory override promotion pass: every composableChildren override key is classified as parent-owned, child-only, or shared
• Master boolean + sub-boolean combinations are merged into single enums (e.g., leadingContent: none, icon, text, iconAndText) instead of being exposed as separate boolean properties
• New validation checklist items verify that parent-owned properties are not buried in sub-component tables and that broad state axes are decomposed

​

Compound component guidance

• New “Critical Rules” quick-reference section at the top of the instruction file highlights the five most commonly violated rules
• New ownership rules table for compound components with tie-breaker heuristics (parent vs child vs both)
• New “Choosing Top-Level vs Nested Rows” section with heuristics for isSubProperty usage
• New “Do NOT” section replaces the former “Common Property Categories” with explicit anti-patterns
• New worked example: Text Field with state axis decomposition, promoted child overrides, and sub-component tables

​

API library updates

• Added compound component ownership guidance with decision table and examples
• Added nested property grouping patterns (trailingContentType → nested label, variant)
• Added showCharacterCount to the Text field canonical API
• Added validationState enum guidance for components with multiple validation-like states

​

uSpec V1.7.3

​

Preferred slot fills for screen reader specs

• create-voice now resolves SLOT preferredValues to local components during extraction and records both preferred instances and default slot children
• Focus-order planning can choose between the default slot content and a representative preferred interactive fill when a slot-hosted control changes the traversal order
• Slot metadata now includes visibility bindings, descriptions, raw keys, and contextual child overrides so the agent can reason about conditional focus stops more accurately

​

Slot-aware artwork rendering

• Screen reader previews now support slotInsertions, allowing the render step to populate slot content before marker resolution and bbox capture
• The focus-order fallback logic reapplies slot insertions while searching for the richest preview state, improving marker placement for slot-hosted actions
• States with zero focus stops still render the component preview, while slot-populated states can now show the correct interactive control instead of a default placeholder scenario

​

Clearer guidance and validation

• The screen reader instruction file now frames focus order as a single top-level section and removes anatomy-specific language from the task definition
• Validation guidance is split into pre-render and post-render checks, including explicit checks for slot-hosted focus stops and slot-populated previews
• implementation.md now documents the voice skill’s preferred-slot extraction and insertion flow alongside the existing SLOT support across other skills

​

uSpec V1.7.2

​

Ownership-aware structure planning

• Section planning now treats subComponents, slotContents, enrichedTree, and layoutTree as discovery inputs instead of final section types
• New ownership resolution classifies each candidate onto exactly one path: subComponent, slotContent, or composition/root-only
• Parent-owned structural roles remain sub-components even when they are placed through a slot or slot-like composition
• Generic library-owned preferred content stays on the slotContent path, and overlapping candidates are deduplicated before any sections are emitted

​

Clearer slot content boundaries

• Slot content sections now render only for preferred instances that still classify as slotContent after ownership resolution
• slotContext is the primary source for hosting-container properties such as sizing mode, padding, and alignment
• The preferred component’s measured self values are used only for placement-specific deltas caused by slot context, not as a second full structure spec
• Section descriptions now explicitly defer component internals to the referenced component spec

​

Stronger validation and authoring guidance

• Validation checks now confirm that every instance still classified as a sub-component is covered after ownership resolution
• Slot-related validation also checks that each surfaced instance is documented on exactly one section path
• Structure guidance adds clearer examples for container-only rows in slot sections and for single-path ownership decisions

​

uSpec V1.7.1

​

Slot-aware API configuration previews

• Configuration examples now support textOverrides — a map of Figma TEXT node layer names to replacement text, applied to the main instance so previews show the example’s actual text instead of default placeholders
• New slotInsertions parameter populates named SLOT nodes with fresh component instances: specify the slot name, a component node ID, and optional nestedOverrides / textOverrides on the inserted child
• All overrides are applied before appendChild into the slot — after adoption, child nodes get compound IDs and become inaccessible (see slot mutation ordering constraint below)
• Extraction returns textNodeMap — an array of { name, characters, parentName } for every TEXT node in the default variant — eliminating guesswork for textOverrides keys

​

Sub-component token ownership (Color)

• New token ownership decision framework in the color instruction file — evaluate each subComponentName entry against four signals (full component vs leaf instance, slot-hosted, parent override) before including or excluding
• Leaf instances (icon fills, divider strokes) stay in the parent spec; full sub-components (buttons, badges, checkboxes) are excluded and noted in generalNotes
• Worked examples table covers common cases (MicroButton → exclude, Chevron icon → include, Divider → include, IconButton → exclude)
• Slot-based component guidance: document default slot content tokens, note slot architecture and preferred instances in generalNotes, explain extraction behavior with nested booleans

​

Composition Pattern B (Structure)

• New Pattern B — Structural map for standalone components or components without a size axis (e.g., Section Heading with leading slot + heading area + trailing slot)
• Uses Spec | Default | Notes columns with group rows for the host container and each structural zone — replaces the need for a separate “container” section
• Boundary rule: when any section says “See X spec”, only document the hosting container (sizing mode, padding, spacing, alignment) — never re-document the component’s own internals
• Slot container properties (sizing mode, alignment, clipsContent) belong as group rows in the composition section, not repeated in each slotContent section
• HUG-sized container guidance: document widthMode: hug instead of reporting measured pixel dimensions, which are artifacts of current content

​

Boolean-toggled previews (Structure)

• New preview type for standalone components with booleans controlling structural elements (slots, accessories, subtext)
• Shows meaningful boolean combinations as labeled instances (e.g., Default, With subtext, Full)
• PROPERTY_OVERRIDES array drives per-column boolean configurations in the preview script

​

Section ID-based rendering (Structure)

• Step 11b now returns the rendered section’s node ID (sectionId)
• Step 11c preview script locates the section by ID instead of by name — eliminates name-collision issues when multiple sections share similar names
• Page context is loaded explicitly via figma.setCurrentPageAsync for stable child traversal

​

Slot-safe tree traversal

• loadAllFonts across API, color, and structure skills now uses a manual recursive collector with per-node try-catch instead of findAll — prevents crashes on SLOT nodes with compound IDs
• Color extraction adds figma.setCurrentPageAsync before traversal for stable child resolution
• enableNestedBooleans and directUnhide in the color skill wrapped with try-catch guards for slot-hosted instances
• implementation.md documents the slot mutation ordering constraint: all mutations on a child instance must happen before appendChild into a SLOT, with code examples for both correct and incorrect patterns, plus the default-slot-child replacement workaround

​

Response truncation guidance (Structure)

• Added guidance for handling MCP response truncation (>~20KB): run targeted follow-up extraction for missing fields instead of re-running the full script

​

uSpec V1.7.0

​

Figma SLOT node support

• Anatomy extraction detects SLOT-type properties, resolves preferredValues to local component nodes, reads componentPropertyReferences.visible for boolean bindings, and surfaces slotDefaultChildren for default content. Step 4 enriches slot notes with preferred component names, marks hidden/empty slots for artwork population, and sets section eligibility for sub-component anatomy sections.
• API extraction collects slotProps with preferred instances and defaultChildren including contextual overrides. Sub-component table defaults now reflect values the designer set in the slot context, not the standalone component’s global defaults. Descriptions reference the source component.
• Property extraction detects boolean-to-slot linkage — when a boolean controls a SLOT’s visibility, the description reads “Controls slot: (accepts: )” instead of the generic “Controls layer”.
• Structure resolves SLOT properties with preferredValues and generates dedicated slotContent sections per preferred component, measuring contextual dimensions when each preferred component is placed inside the slot across all parent sizes.
• Voice deep-recurses into SLOT nodes during extraction so interactive elements inside slots appear as separate focus stop entries for merge analysis. Reads slotVisibility for conditional focus stop detection across states.

​

Nearest-edge marker placement with collision avoidance

• Replaces the previous clockwise / left-stagger / alternating strategy system with a unified nearest-edge algorithm across anatomy, per-child, and voice skills
• For each element, all four sides are scored by distance to the component boundary — the marker is placed on the shortest side
• Before placing, overlap with already-placed markers is checked (8 px minimum gap); on collision, perpendicular offsets are applied, falling back to the next-best side if bounds are exceeded
• Inline markers for nested elements — elements visually contained inside another annotated element get a short stub line (16 px) on their nearest edge instead of a perimeter marker

​

Component-relative spec placement

• Specs are now placed on the same page as the source component, positioned to its right with a 200 px gap — no more viewport-center placement
• The script resolves the component node, walks up to its PAGE ancestor, activates the page, and positions the frame at compNode.x + compNode.width + 200
• Cross-file destination URLs retain the existing viewport-center behavior

​

Completion link

• Every skill now prints a clickable Figma deep-link URL to the rendered spec frame at the end of the run
• URL format: https://www.figma.com/design/{fileKey}/?node-id={frameId}

​

Improved example rendering

• Dynamic font loading (loadAllFonts) runs after every mutation that may reveal new text nodes — createInstance, setProperties, appendChild into slots, and directUnhide — preventing “unloaded font” errors on components using non-template fonts
• Font-family fallback (loadFontWithFallback) discovers exact font style strings via listAvailableFontsAsync instead of hardcoding style names, with graceful fallback through preferred → fallback → first-available → Inter
• Template font loading moved from hardcoded family to discovery from existing marker and section text nodes
• API configuration example preview now finds SLOT nodes via findOne(n => n.type === 'SLOT') instead of assuming children[0]

​

Variant selection evaluation (Anatomy)

• New Step 4 sub-step 0 evaluates whether the default variant is the best representative — when it yields only 1–2 elements and variant axis option names suggest a structurally richer alternative, the extraction re-runs with PREFERRED_VARIANT_PROPS
• Does not re-extract for purely stylistic differences (color, size, theme)

​

Brief description header

• Anatomy and property specs now compose a 1-sentence briefDescription (max ~15 words) describing what the component IS and does, placed in the #brief-component-description header field
• Replaces the previous generic “Anatomy breakdown of…” and “Configurable properties of…” text

​

Root container detection (Anatomy)

• New childContainerIsVariant flag indicates when the extraction traversed past the root container — a synthetic container element is always inserted when traversal occurred
• When the root container was not traversed, the agent evaluates architectural significance (composable slots, conditional visibility, mixed layout) to decide whether annotation is warranted
• hasStrokes on the root variant no longer triggers a separate synthetic element — strokes are described in the container note instead

​

Voice rendering improvements

• Removed artworkLabels and the detach-and-replace-text workflow — artwork instances stay live throughout rendering
• findStopNode now uses ancestor-aware visibility matching (isEffectivelyVisible) for the Focus Order entry, correctly triggering the richest-variant fallback when boolean-enable alone cannot surface all focus stops
• Preview wrapper width reads from previewPlaceholder.width to match the template layout instead of computing independently
• Conditional focus stops and disabled/non-focusable states documented in merge analysis guidance

​

uSpec V1.6.2

​

FRAME-wrapped TEXT detection (Anatomy)

• Frames containing a single TEXT child are now classified as text instead of container — the frame name is preserved in originalName and the element carries nodeType: 'TEXT'
• Short text content (up to 30 characters) is included in the element notes for richer context in the attribute table
• Applies to both extraction and the name / originalName documentation in the instruction file

​

Frame icon indicator (Anatomy)

• New #frame indicator icon for FRAME and GROUP node types, added alongside the existing #instance, #text, and #slot icons
• Applied to both composition-level and per-child artwork rendering scripts — FRAME/GROUP elements now display their own icon instead of falling through to the default (no icon) case

​

Name field semantics (Anatomy)

• name now consistently returns the designer-facing layer name across all classifications
• For instance-unwrapped elements, name is the wrapper frame’s name (e.g., “Thumb”) — the inner component name is available via wrappedInstance.componentSetName
• Previously, unwrapped instances overwrote name with the inner component’s componentSetName, losing the original frame label

​

Effect style consolidation (Color)

• When a node has an effectStyleId, extraction now emits a single "effect style" entry with the style name as the token, instead of iterating individual shadow layers
• Individual drop shadow / inner shadow entries are still emitted when no effect style is applied
• The variantColorData contract documents the new "effect style" property value and its semantics

​

Effect and elevation token category (Color)

• Added Effect/Elevation row to the token-naming reference table with common style names (low, medium, high)
• Added Effects row to the element-naming reference table with common layer names (Shadow, Elevation, Drop shadow)

​

uSpec V1.6.1

​

Wrapper frame for artwork (Anatomy)

• Artwork elements (component instance, outlines, markers, lines) are now placed inside a dedicated inner wrapper frame instead of directly on the preview placeholder
• The wrapper uses layoutMode = 'NONE' with transparent fills and clipsContent = true, keeping absolute positioning isolated from the template’s auto-layout
• Applied to both composition-level and per-child artwork scripts

​

Dynamic preview sizing (Voice)

• Preview dimensions are now calculated from the live instance’s width/height plus marker margins, replacing the stale ROOT_SIZE parameter
• Eliminates centering drift when variant switching changes the component’s rendered size
• Sizing formula accounts for the number of focus stops so left-stagger markers never run out of room
• Removed the ROOT_SIZE placeholder from the rendering template and instruction file

​

Marker positioning strategies (Voice)

• Voice artwork now uses the same three-strategy marker placement as anatomy: clockwise, left stagger, and alternating
• Strategy is auto-detected by clustering focus stop centers — consistent with anatomy’s approach
• Replaces the previous simple alternating-only placement, producing cleaner annotations for concentric and vertically stacked components

​

Pre-detach bounding box capture (Voice)

• Bounding boxes for focus stops are now captured from the live instance before any detachInstance() call
• Avoids fragility of post-detach name matching where SLOT nodes reorganize and findStopNode may fail

​

uSpec V1.6.0

​

Measurement annotation paused (Structure)

• Temporarily removed measurement annotations (TOKEN_MAPS, annotateNode, and all native Figma addMeasurement calls) from the structure skill
• The addMeasurement API is not yet exposed through Figma MCP — annotations will return once native support is available
• Table-driven spec rows and token references are unaffected; only the visual measurement lines on preview instances are paused

​

Synthetic element detection (Anatomy)

• New hasVisuals() utility detects fills, strokes, and effects on any node — used to identify visually meaningful frames that wrapper traversal would otherwise skip
• rootVariantVisuals and traversedFrames are now returned by the extraction script, surfacing visual layers (statelayers, backplates, shape containers) that exist on the root variant or intermediate wrapper frames
• Step 4 inserts synthetic elements (isSynthetic: true) for skipped visual layers, with re-indexing — concentric components like checkbox now show all structural layers in the anatomy table
• Instruction file adds note-writing guidelines, worked examples, and validation checklist items for synthetic elements

​

Clockwise marker placement (Anatomy)

• Three marker placement strategies based on element center clustering: clockwise (concentric/overlapping), left stagger (vertical stack), and alternating (mixed layouts)
• Clockwise strategy rotates markers around the component (left → top → right → bottom) — ideal for concentric components where all elements share the same center
• Both composition and per-child artwork scripts use the same isClustered detection and strategy selection

​

Richest variant fallback (Anatomy)

• When the default variant produces 0 elements after wrapper traversal (e.g., an unchecked checkbox with an empty structure frame), extraction falls back to the variant with the most descendant children
• selectedVariantId is returned by extraction and reused by the rendering step, ensuring artwork matches the extraction data
• resolveChildContainer refactored into a reusable function shared by the fallback logic

​

Icon and component references (Structure)

• INSTANCE children now carry parentSetName — the component set name (e.g., "checkmark", "chevron-down") — at all tree depths, not just depth 0
• New iconName / leadingIcon / trailingIcon spec rows document which component is used, placed before the corresponding size row
• Instruction file adds a Component References section, decision-table entry, common-mistake warning, and validation checklist item

​

Two-layer skill architecture

• SKILL.md is now strictly the orchestration layer — step-by-step workflow, MCP adapter mapping, Plugin API scripts, script output contracts, intermediate data structures, and template mechanics
• Instruction files are now strictly the domain knowledge layer — interpretation guidance, decision frameworks, naming conventions, value formatting rules, worked examples, edge cases, and validation checklists
• Every skill retains its two-tier extraction model: deterministic scripts for data gathering, AI reasoning for interpretation and enrichment

​

Housekeeping

• Deleted data-example.json — no longer referenced by any skill
• Updated api/api-library.md with improved reference patterns
• Updated implementation.md with variant selection and marker positioning docs

​

uSpec V1.5.0

​

Composable slot support across skills

• New slot classification type in the anatomy extraction script — SLOT nodes are detected, traversed, and annotated with a dedicated #slot indicator in the table
• Slot traversal added to all three wrapper-walking paths (extraction, composition artwork, per-child artwork) so components using Figma’s composable slot pattern are handled consistently
• Voice/screen reader extraction recurses into slot containers with identically-named children, assigning slotIndex for index-based matching across focus stop resolution

​

Composition-level deduplication

• Multiple instances of the same sub-component (e.g., 4 buttons in a button group) are collapsed into a single representative element with an (xN) suffix at the composition level
• Prevents redundant markers, outlines, and table rows — one entry per unique sub-component, with a note explaining the repeated pattern
• Per-child sections are also deduplicated by mainComponentSetId so only one anatomy section is created per unique sub-component

​

Blown-out child rendering (property skill)

• New rendering mode creates instances directly from a child’s component set instead of modifying nested instances in a parent — immune to sparse variant matrices and nested-instance property access issues
• Automatic fallback: when setProperties() fails on a nested instance, the chapter is re-rendered in blown-out mode
• Sparse variant matrix detection added to AI validation — identifies missing axis combinations and adds constrainedBy metadata for correct base variant selection
• Coupled axis detection improved with heuristics for semantically coupled axes where option names differ

​

Artwork label replacement (voice skill)

• Artwork previews now replace generic “Label” placeholder text with realistic, state-specific labels (e.g., “Day”, “Week”, “Month”, “Year”)
• Labels are passed per-state via artworkLabels and applied by detaching the instance and its nested sub-instances before modifying text nodes
• Focus stop outlines (pink dashed rectangles) added to voice artwork for visual consistency with the anatomy skill

​

Color token resolution improvements

• Token resolution now prefers codeSyntax.WEB over raw variable names, producing cleaner developer-ready token references
• Paint style fallback added for fills, strokes, and effects — when no variable binding exists but a Figma paint style is applied, the style name is used as the token
• Container/slot component detection: when the parent has no direct color entries, extraction re-targets to the sub-component automatically
• Mode token maps updated to use web code syntax

​

API child overrides for slot components

• Configuration examples now support childOverrides — per-child property overrides applied to composable slot children by index
• Item-level properties (e.g., item 1 isSelected) can be documented in example tables to reflect the preview state

​

Figma MCP compatibility (property skill)

• Added method restriction table and replacement helpers (findByName, findAllText, font-loading via tn.fontName) for figma-mcp where findAll, findOne, and getRangeAllFontNames throw TypeError
• Page-loading block updated to use explicit page name lookup instead of parent traversal

​

User-provided design context

• Anatomy and property skills now integrate user-provided notes (behavioral descriptions, usage constraints, coupling hints) into semantic notes and validation logic
• Voice skill documents behavioral states from user context (e.g., single-select vs. multi-select) as separate entries when they produce different semantic properties

​

Robustness

• Font loading wrapped in try/catch across all rendering scripts to prevent crashes on mixed-font or empty text nodes
• Instance-wrapper terminology standardized from “slot-wrapper” to “instance-wrapper” across all skills and instruction files

​

uSpec V1.4.1

​

Dual MCP documentation

• All references to “Figma Console MCP” replaced with MCP-agnostic phrasing throughout spec pages, diagrams, and prerequisites
• Architecture overview in How It Works rewritten to show both MCP paths in a single diagram
• Mermaid diagrams across all 7 spec pages and the How It Works page updated to use generic “Figma MCP” nodes
• Removed tool-specific labels (figma_execute) from diagram nodes — tool names are implementation details

​

Expanded troubleshooting

• Figma connection troubleshooting restructured into Console MCP and Native Figma MCP tabs
• Added native MCP troubleshooting for connection issues, token validation errors, and file/node resolution
• Updated multiple-agent guidance to cover both MCP models

​

Pre-verification callout

• Added a prominent warning between MCP setup and firstrun in Getting Started — test your MCP connection before running firstrun
• MCP-specific verification instructions with links to each provider’s documentation

​

MCP documentation freshness notices

• Added notes throughout setup and troubleshooting pages reminding readers that MCP providers update their instructions frequently
• Direct links to Figma Console MCP docs and native Figma MCP docs wherever configuration is discussed

​

Global navigation

• Removed the Figma Console MCP anchor from the global nav — with dual MCP support, a single provider link is misleading

​

uSpec V1.4

​

Consolidated extraction script

• A single figma_execute call (Step 4b) replaces the previous multi-step flow (token extraction + separate boolean enrichment + separate axis classification), handling everything in one pass
• The script walks the component tree, resolves color variable bindings, classifies variant axes by token fingerprint, detects boolean-gated elements, and discovers mode-controlled collections

​

Sub-component tagging

• Nested instances are now tagged with their parent component set name, producing richer and more descriptive element labels in the output tables

​

Nested boolean enablement

• Live preview instances now show all optional elements (icons, prefix/suffix, clear button, hints) by recursively enabling boolean properties on nested instances, so the artwork matches the documented tokens

​

Updated AI interpretation layer

• Step 4c strategy selection logic is clearer — the two-gate model (variant count and token similarity) now has explicit thresholds and reasoning guidance for choosing Strategy A vs Strategy B

​

uSpec V1.3

​

More detailed screen reader output

• Focus stop discovery uses deep traversal (findOne) instead of shallow children lookup — correctly resolves nested elements like a clear button inside an Input child instance
• Focus Order artwork now maximizes element visibility: boolean properties are force-enabled and the richest state variant is selected automatically, so all documented focus stops appear in the preview even when the default variant hides some of them
• booleanDefs extracted alongside variantAxes in the component scan, giving the rendering step full knowledge of toggleable sub-elements

​

Fewer tokens via state grouping

• States with identical accessibility semantics (same focus stops, roles, labels, and announcements) are collapsed into a single entry with a combined title — e.g., “Text field Enabled / Pressed / Active” instead of three separate sections
• Cuts redundant output for components like Text field that have many visual-only state differences but identical screen reader behavior
• Guidance added to both the skill workflow and the agent instruction file, with a new validation checklist row and common-mistake entry

​

Housekeeping

• Added FONT_FAMILY placeholder to the rendering template for consistent font resolution across specs

​

uSpec V1.2

​

Smarter measurement annotations

• Padding and spacing now use Figma’s native measurement display instead of custom text labels — cleaner output with no mislabeled annotations
• Min/max constraints show actual node values (e.g., min 32, max 200)

​

Template-driven previews

• Preview layout is defined by the template; the script no longer overrides direction or spacing
• Section template hidden by default, eliminating an extra manual step

​

Clearer agent instructions

• Removed ambiguous language that caused layout direction changes
• Updated validation rules for new measurement behavior

​

Deterministic vs AI split (~60/40)

• ~60% deterministic scripts handle extraction, cross-variant comparison, and rendering
• ~40% AI reasoning handles section planning, design-intent notes, and anomaly detection
• Output is highly consistent across runs

​

uSpec V1.1.0

​

Multi-platform support

• Claude Code CLI and Codex CLI are now supported as agent hosts alongside Cursor
• New firstrun skill handles environment setup — run /firstrun in Claude Code or $firstrun in Codex to get started
• Skills are deployed to the chosen platform on demand, keeping each environment clean
• CLAUDE.md and AGENTS.md provide platform-specific project instructions

​

Improved layer detection

• Anatomy and Property skills now handle complex component structures with better layer detection and classification
• More accurate marker placement for deeply nested or auto-layout-heavy components

​

Infrastructure

• sync-skills.sh supports --target flag for platform-specific skill deployment
• uspecs.config.json now stores the active environment alongside template keys
• .gitignore updated to keep generated skill copies out of version control

​

uSpec V1

​

Spec types

• Anatomy: numbered markers and attribute tables for component structure, with AI-driven element classification, per-child sections, and property-aware unhide
• Properties: variant axes, boolean toggles, variable mode exhibits, and child component chapters with live instance previews
• API: property tables with values, defaults, required status, sub-component tables, and configuration examples
• Color Annotation: design token mapping for fills, strokes, and shadows across states and variants, with automatic strategy selection
• Structure: dimensions, spacing, and padding across density, size, and shape variants with token references
• Screen Reader: VoiceOver (iOS), TalkBack (Android), and ARIA (Web) accessibility specs with focus order and merge analysis
• Motion: animation timeline bars and easing detail tables from After Effects keyframe data, with pre-computed segments and color-coded easing visualization

​

Infrastructure

• Agent skills architecture running in Cursor via .cursor/skills/
• Figma Console MCP integration for real-time component data extraction
• Template library system with one-time @firstrun configuration
• Documentation site at docs.uspec.design