Changelog

​

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