Tessellate

Verified design-to-implementation for teams using Figma, design systems, and AI coding agents.

Tessellate connects Figma work to the implementation context a design-system team already owns: component mappings, token rules, source paths, content sidecars, asset references, font requirements, verification recipes, and buyer-facing proof reports.

Tessellate is the verification layer and repo-aware source map between Figma, design systems, and AI agents. It does not ask teams to trust generated UI. It gives them a receipt: what the Figma source said, what the implementation rendered, where parity held, what blocked parity, and what to fix next.

This repository is the product and integration surface for Tessellate. It contains docs, schemas, examples, and neutral registry fixtures that teams can use to configure the product around their own design system.

Product

Tessellate is one system:

Capability	What it does
Tessellate Code	Shows repo-aware implementation context for mapped Figma nodes in Dev Mode
Inlay	Applies user-configured brand-font substitution inside Figma Desktop
Surface	Translates selected components, sections, pages, windows, or documents into scoped handoff artifacts
Surface Receipt	Reports visual parity, source mapping, unresolved fonts/assets, confidence, and the implementation fix list
Source map	Links rendered regions back to Figma nodes, code, mappings, tokens, fonts, assets, and diagnostics
Design System Drift Map	Audits files for unmapped components, rogue fonts, token mismatches, repeated patterns, and unreachable assets
CI receipt gate	Publishes receipts on implementation reviews and fails above the configured parity threshold
Curations	Publishes per-curation token, CSS variable, mapping, preview, and copy-truth contracts for multi-brand systems, including headless Figma REST publish from CI
Doctrine Compiler	Compiles prose brand doctrine into validated doctrine.json contracts for later critique, consistency, motion, and generation gates
Optical Refinement Pass	Emits reversible typography, baseline, kerning, type-scale, and OpenType diffs for selected Figma frames
Visual-Quality Critic	Scores selected Figma frames against deterministic doctrine-backed axes and optional floor thresholds
Cross-Surface Consistency	Compares numbered curation surfaces against kit centroid fingerprints and optional cascade render pairs
Brand-Input Theming	Maps reviewed brand inputs into generic role slots, APCA-safe foregrounds, logo variants, tokens, CSS variables, and per-surface theme files
Responsive Authoring	Derives multi-viewport frame specs and operation plans from a source Figma frame without mutating Figma through REST
Motion Authoring	Plans doctrine-bound motion tokens, microinteraction specs, ban diagnostics, and GIF preview evidence without mutating Figma through REST
Imagery Pipeline	Plans art-directed image-slot matches, provider asset selections, provenance diagnostics, and grade manifests without mutating Figma through REST
Curation Design Memory	Stores approved and rejected Figma node precedents as versioned, committable records with queryable warnings
Component Extraction	Proposes typed TSX components and mapping registry entries from selected Figma frames for review
Layout-Distinctness Generator	Emits reviewable candidate frame specs and a distinctness matrix for generic layout proposals
Full-Kit Generation	Orchestrates compose, refine, imagery, motion, responsive, critique, and configured kit gates into per-surface and per-pass reports plus kit-manifest.json
Tessellate Connect	Scans repos, emits GitHub App contracts, and serves MCP tools for context, receipt checks, and repair workflows
Config Validation	Publishes schemas, examples, and offline validation for adopter-authored craft config before Figma-backed runs
Repo context	Reads customer-owned registry, token, component, font, and asset metadata
Agent handoff	Produces structured bundles an engineer, MCP host, or AI agent can apply without guessing

Install

Use the official Tessellate distribution channel for your workspace. That may be a Figma workspace/plugin install link, a beta distribution link, or an organization-managed plugin release. The installable product includes Tessellate Code, Inlay, Surface, repo context, and handoff export.

For headless curation publishing in CI, install the CLI from a pinned GitHub tag:

npm install --global github:kfrrst/tessellate#v0.8.1
tessellate --version

Scan a repo into a Tessellate Connect report:

tessellate connect scan \
  --repo ./packages/design-system \
  --out ./connection-report.json \
  --package @example/design-system \
  --max-files 5000 \
  --json

The report is read-only evidence for a future GitHub App, remote MCP server, CI receipt gate, or repair workflow. It detects component candidates, token and CSS sources, fonts, assets, Storybook, CI workflows, ignored secret files, and the minimum permission shape needed to post receipt checks.

Generate the GitHub App manifest and hosted worker contract from that report:

tessellate connect github-app \
  --connection ./connection-report.json \
  --app-name "Tessellate Receipts" \
  --callback-url "https://connect.example.com/github/callback" \
  --setup-url "https://connect.example.com/setup" \
  --webhook-url "https://connect.example.com/webhooks/github" \
  --manifest-out ./github-app-manifest.json \
  --worker-out ./worker-contract.json \
  --json

The generated manifest uses least-privilege receipt permissions: contents: read, metadata: read, pull_requests: write, and checks: write. The worker contract keeps installation and user actors separate, forbids token passthrough, and maps receipt work to the same standalone CLI commands used by CI and MCP hosts.

Run the local MCP stdio server for hosts that need tool-callable Tessellate reports:

tessellate mcp serve \
  --repo ./packages/design-system \
  --max-output-bytes 1000000

The server speaks newline-delimited JSON-RPC over stdin/stdout and exposes tools for repo context, GitHub App contract generation, config validation, parity reports, kit generation, repair suggestions, and guarded PR creation. Write-capable PR creation is refused unless the server is started with --allow-write.

Run the remote HTTP/OAuth host when a hosted MCP client should call the same tool engine over authenticated HTTP:

tessellate mcp http \
  --repo ./packages/design-system \
  --issuer "https://auth.example.com" \
  --audience "https://connect.example.com/mcp" \
  --resource "https://connect.example.com/mcp" \
  --jwks-url "https://auth.example.com/.well-known/jwks.json" \
  --read-scope tessellate:read \
  --write-scope tessellate:write

The HTTP host exposes POST /mcp, GET /.well-known/oauth-protected-resource, and GET /healthz. It validates Bearer JWT issuer, audience, expiration, signature, and scopes before dispatching to the same MCP tools. RS256 JWKS is intended for production OAuth providers; --jwt-secret-env is available for private HS256 deployments and tests.

Validate config without Figma before running craft commands:

tessellate config list-kinds
tessellate config validate ./type-scale.json --kind type-scale --json
tessellate config validate ./surfaces.json --kind surfaces --json

Licensed-font preview rendering uses adopter-owned font URLs:

tessellate render-previews \
  --curation-dir ./public-mirror \
  --slug reference \
  --url-template "https://preview.example.com/{surface}?curation={slug}" \
  --fontset ./fontset.json \
  --font-coverage-source ./figma-tree.json \
  --coverage-report ./font-coverage.json \
  --font-policy strict

Tessellate injects @font-face at render time and never hosts or redistributes font binaries.

Whole-kit preview coverage uses a per-surface target map:

tessellate render-previews \
  --curation-dir ./public-mirror \
  --slug reference \
  --targets ./targets.json \
  --report ./render-coverage.json

Email preview coverage uses configured client adapters and repo-owned HTML sources:

tessellate render-previews \
  --email \
  --curation-dir ./public-mirror \
  --clients ./clients.json \
  --email-source ./email-source.json \
  --slug reference \
  --dark-mode true \
  --report ./email-render-report.json

This is an adapter contract for email-classified curation surfaces. Tessellate does not implement a proprietary email engine; each client entry invokes the team's chosen renderer and reports artifacts, warnings, and failures through JSON.

Curation copy checks flag fabricated claims and vertical-specific nouns before mock copy ships as fact:

tessellate copy-check <figma-file-key> \
  --surfaces-file ./tessellate-surfaces.json \
  --terminology ./terminology.json \
  --claims ./claims.json \
  --pages "00..13" \
  --threshold strict \
  --out ./copy-report.json

The command reads the Figma REST file tree with FIGMA_TOKEN by default and scans text layers for the configured curation surfaces. Use --threshold warn to write the same JSON report without failing CI.

Materiality checks detect banned visual treatments and report permitted application cues before a kit ships:

tessellate materiality <fileKey:nodeId> \
  --profile ./materiality-profile.json \
  --threshold strict \
  --out ./materiality-report.json

The command reads GET /v1/files/:fileKey through Figma REST using FIGMA_TOKEN by default. Use --figma-token-env <NAME> for another secret name and --figma-api-base-url <url> only for tests or private API proxies. It is deterministic and read-only: banned treatments such as glassmorphism, neumorphism, gradient mesh, and fake paper are controlled by the profile. Profiles can also add custom banned IDs with deterministic detect predicates; unsupported banned IDs are surfaced as warnings rather than silently ignored. Permitted cues such as groundTint, grain, and paperDepthShadow are role-targeted by profile names and appliesTo rules. Passing --apply true marks apply-requested candidates in the JSON report for plugin, MCP, or write-capable bridge consumers; the CLI does not mutate Figma through REST.

Brand doctrine compilation turns a reviewed Markdown doctrine into a validated machine-readable contract:

tessellate doctrine compile ./brand-doc.md \
  --schema ./doctrine.schema.json \
  --map ./section-map.json \
  --out ./doctrine.json \
  --strict

--schema is required and validates the compiled contract. --map is optional when the document headings already match the schema sections. --out defaults to doctrine.json; --strict fails on unmapped required sections and schema validation errors. See Doctrine Compiler.

Optical refinement checks selected Figma frames against an adopter-owned type scale and baseline grid:

tessellate refine \
  --frame "$FIGMA_FILE_KEY:$FIGMA_NODE_ID" \
  --scale ./type-scale.json \
  --baseline 4 \
  --kerning optical \
  --opentype liga,smcp,onum \
  --out ./refinement-diff.json \
  --dry-run

The first CLI release reads the selected Figma file tree through Figma REST and emits a deterministic reversible diff. Passing --apply true marks apply-requested changes in the JSON output for plugin, MCP, or write-capable bridge consumers; the CLI does not mutate Figma through REST. See Optical Refinement Pass.

Visual-quality critique checks a selected Figma frame against reviewed doctrine:

tessellate critique \
  --frame "$FIGMA_FILE_KEY:$FIGMA_NODE_ID" \
  --doctrine ./doctrine.json \
  --floors ./critique-floors.json \
  --out ./critique-report.json \
  --json

The first CLI release provides deterministic doctrine-backed axes from Figma REST/node-tree data. Optional VLM scoring is not implemented yet and should be layered later as an additional scoring provider, not as a replacement for the deterministic report. The command exits non-zero on fail verdicts. See Visual-Quality Critic.

Cross-surface consistency checks a numbered curation kit for surfaces that drift from the kit's shared system:

tessellate consistency \
  --curation reference \
  --surfaces "$FIGMA_FILE_KEY" \
  --surfaces-file ./tessellate-surfaces.json \
  --pages "00..13" \
  --registry-file ./component-mappings.json \
  --tolerance 0.15 \
  --cascade-states on,off \
  --cascade-renders ./cascade-renders.json \
  --out ./consistency-report.json \
  --json

The first CLI release reads the Figma REST file tree and computes per-surface fingerprints for type scale, color-role usage, spacing rhythm, motifs, photo/register hints, grid columns, and mapped components. It computes a kit centroid and flags surfaces beyond tolerance. Cascade checks verify provided render pairs only; the CLI does not capture browser renders in this release. See Cross-Surface Consistency.

Brand-input theming maps a reviewed brand packet onto numbered curation surfaces and writes APCA-safe theme artifacts:

tessellate theme \
  --brand-inputs ./inputs.json \
  --curation reference \
  --surfaces "$FIGMA_FILE_KEY" \
  --surfaces-file ./tessellate-surfaces.json \
  --pages "00..13" \
  --out ./public-mirror \
  --contrast-report ./contrast-report.json \
  --apca-floor-body 60 \
  --selector-attribute data-curation \
  --css-variable-prefix curation \
  --figma-api-base-url "https://api.figma.com" \
  --figma-token-env FIGMA_TOKEN \
  --json

The command reads logo variants, colors, photos, optional role overrides, and ink/paper candidates; detects solid Figma page backgrounds; maps raw colors into generic role slots; chooses APCA-safe foregrounds and matching light/dark logo variants; and emits themed tokens, CSS variables, per-surface theme files, and a manifest. See Brand-Input Theming.

Responsive authoring derives target frame specs and operation plans from a source Figma frame:

tessellate responsive \
  --frame "$FIGMA_FILE_KEY:$FIGMA_NODE_ID@1440" \
  --to 768,375 \
  --rules ./reflow.json \
  --out ./responsive-report.json \
  --json

The first CLI release reads Figma through REST and emits generated frame specs and operation plans for plugin, MCP, or write-capable consumers. It does not mutate Figma through REST. Reflow rules control grid columns per viewport, typeScalePerViewport, navSwap, heroRecrop, spacingDensity, and gridCap; generated variants are named like <frame name>@768 and <frame name>@375. See Responsive Multi-Viewport Authoring.

Motion authoring plans doctrine-bound motion and microinteraction artifacts for a selected Figma frame:

tessellate motion \
  --frame "$FIGMA_FILE_KEY:$FIGMA_NODE_ID" \
  --choreography ./motion.json \
  --export gif,specs \
  --out ./motion-spec.json \
  --preview-out ./motion.gif \
  --json

The first CLI release reads Figma through REST and emits deterministic motion tokens, production specs, ban diagnostics, and GIF preview evidence for review. It does not mutate Figma through REST. Choreography files define generic interaction roles, timing, easing, reduced-motion behavior, and banned motion classes for any brand or design system. See Motion And Microinteraction Authoring.

Art-directed imagery planning matches reviewed creative briefs to Figma image slots and writes a placement manifest:

tessellate imagery \
  --brief ./brief.json \
  --register editorial \
  --provider ./provider-assets.json \
  --grade ./look.cube \
  --place "$FIGMA_FILE_KEY" \
  --out ./imagery-manifest.json \
  --json

The first CLI release reads Figma through REST and emits image-slot matches, provider asset selections, provenance diagnostics, grade references, and placement operations for plugin, MCP, or write-capable consumers. It enforces one visual register and one LUT grade for the run, validates provenance and synthetic-image flags, blocks stock assets from hero slots, and does not mutate Figma through REST. See Art-Directed Imagery Pipeline.

Curation design memory records approved and rejected Figma node precedents:

tessellate memory add \
  --pattern "$FIGMA_FILE_KEY:$FIGMA_NODE_ID" \
  --verdict approved \
  --store ./tessellate-memory \
  --surface storefront_hero \
  --register editorial \
  --reason "Strong reusable hierarchy and image-slot treatment" \
  --tags hero,image-led \
  --json

Query returns ranked approved and rejected precedent, warning when rejected matches appear:

tessellate memory query \
  --store ./tessellate-memory \
  --surface storefront_hero \
  --register editorial \
  --tags hero,image-led \
  --top 5 \
  --out ./memory-query-report.json \
  --json

The first CLI release reads Figma REST for memory add, writes versioned committable JSON records plus deterministic thumbnail placeholder metadata and artifacts, and requires --reason for rejected records. See Curation Design Memory.

Component extraction proposes TSX and mapping artifacts from a selected Figma frame:

tessellate extract \
  --frame "$FIGMA_FILE_KEY:$FIGMA_NODE_ID" \
  --to ./packages/design-system \
  --name ProductCard \
  --infer-props true \
  --code-connect true \
  --registry ./mapping-registry.json \
  --out ./extract-report.json \
  --json

The first CLI release reads Figma REST, infers typed props from text slots, image/media slots, repeated children, and variant-like child frames, writes a reviewable TSX component proposal under the target package, writes or updates a component-mapping proposal, and emits extract-report.json. It is a proposal and review workflow; it does not run arbitrary code, commit files, or mutate Figma through REST. See Component Extraction.

Layout-distinctness generation proposes structurally distinct candidate frame specs for a generic surface:

tessellate compose \
  --surface <name> \
  --direction <direction.json> \
  --brand <brandInputs.json> \
  --n 3 \
  --distinct-from <slugs> \
  --out <distinctness-matrix.json> \
  --recolor-floor 0.6 \
  --existing-kits <existing.json> \
  --frames-dir <dir> \
  --json

The command is a headless, generic proposal and generation workflow. It emits reviewable candidate frame specs plus a distinctness matrix, uses color-blind structural scoring as a generation constraint, applies the configured recolor floor, and does not mutate Figma through REST. MCP parity is the stable CLI/JSON I/O contract. See Layout-Distinctness Generator.

Full-kit generation orchestrates already-shipped standalone passes into a publish-ready kit manifest:

tessellate kit generate \
  --direction <direction.json> \
  --brand <brandInputs.json> \
  --surfaces <surfaces.json> \
  --doctrine <doctrine.json> \
  --out <kit-manifest.json> \
  --gate critique,consistency,a11y,copy-check \
  --stop-on-fail \
  --workdir <dir> \
  --json

The command delegates to compose, refine, imagery, motion, responsive, critique, and configured kit gates; emits per-surface and per-pass reports plus kit-manifest.json; and sets publishReady to true only when every required surface pass and every configured kit gate passes. It stays generic, does not mutate Figma through REST, and exposes MCP parity through stable CLI/JSON I/O. See Full-Kit Generation.

Before/after parity reports compare two renders of the same surface:

tessellate parity \
  --a ./reference/storefront-hero.png \
  --b ./previews/reference/01-storefront-hero.png \
  --mode design-vs-impl \
  --threshold 0.02 \
  --out ./parity-report.json

See Install and Connect for the customer setup flow. Repo owners should prepare the metadata described in Repo Setup Contract before filling out plugin settings.

Connect Your Repo

Tessellate is configured by URLs or files your repo owns:

Input	Purpose
Mapping registry	Figma node/component mappings for Tessellate Code
Surface design-system context	Component paths, import roots, token rules, naming conventions, fonts, and media destinations
Inlay profile or profile set	Font substitution rules for the user's installed fonts
Repo URL	Source links and generated handoff references
MCP/local bridge	Optional explicit path for writing Surface handoff files into a local checkout

In Figma, open Plugins -> Tessellate -> Settings - connect repo... to save the registry URL, Surface context URL, repo URL, and optional Inlay profile. Project configs can expose named Inlay profiles and optional page/file rules so Settings shows a governed picker instead of asking every user to type profile URLs by hand.

Surface contexts can share font-source metadata with an Inlay profile so renderers know whether a family/style is backed by a repo path, raw URL, CSS URL, package, or local installation note before visual comparison.

Start with:

• Install and Connect
• Repo Setup Contract
• Mapping Registry
• Inlay
• Surface
• Surface Receipts
• Figma Source Map
• Design System Drift Map
• CI Receipt Gate
• Agent Handoff
• Curations
• Doctrine Compiler
• Optical Refinement Pass
• Visual-Quality Critic
• Cross-Surface Consistency
• Brand-Input Theming
• Responsive Multi-Viewport Authoring
• Motion And Microinteraction Authoring
• Curation Design Memory
• Component Extraction
• Layout-Distinctness Generator
• Full-Kit Generation
• Quality Substrate
• Production Quality Roadmap
• Quality report schema
• Doctrine schema
• Surface design-system context schema
• Example Surface context

Repository Layout

Path	Contents
docs/	Product and integration docs
schemas/	JSON schema contracts for repo-owned configuration
examples/	Neutral example design-system context
mappings/	Neutral example mapping registries
scripts/	Product posture checks

Releases

Tessellate uses a single repository version in VERSION. Maintainers publish GitHub Releases through the manual Release workflow after the product contracts, docs, examples, and release-governance checks pass.

Each release uses a vX.Y.Z tag and generated release notes so downstream systems can watch the repository release feed instead of scraping branches.

Platform Posture

Tessellate stays inside the supported Figma plugin model:

• Uses Figma's official plugin and codegen APIs.
• Runs from explicit user actions and Dev Mode selection changes.
• Fetches user-configured registry or context URLs with user awareness.
• Keeps external connections and data handling documented.
• Does not authenticate to host product services without explicit user setup.
• Does not load executable plugin code from arbitrary remote URLs at runtime.

For review-sensitive deployments, keep copy focused on design-system handoff, implementation context, parity evidence, remediation, and repo-owned metadata.

Support

Use this repository for product docs, integration contracts, issues, examples, and discussion around Tessellate configuration.

License

All rights reserved. See LICENSE.