integration-craft

name	integration-craft
description	Institutional knowledge for Styleframe's tooling and seams — plugin architecture (virtual modules, importree HMR, recipe tree-shaking) across 9 bundlers, CLI conventions, DTCG/Figma sync, the changesets release train, packaging traps, and deploy configs. Consult before every tooling/**, config/**, .github/**, or release task.

Integration craft

Styleframe's promise is "works with your stack." This skill maps every seam where that promise is kept — and where it has historically broken.

This seat also owns the root workspace config (package.json, pnpm-workspace.yaml, pnpm-lock.yaml, turbo.json): dependency and orchestration changes route here. Other seats' PRs may update the lockfile as a side effect of their own dependency changes; structural root-config changes are yours.

Plugin (tooling/plugin) — the unplugin core

• One unplugin factory (src/plugin.ts), virtual-module resolution in src/virtual-modules.ts, per-bundler adapters: vite, webpack, rollup, esbuild, nuxt, astro, rspack, farm, bun — adapters are default exports, consumed as styleframe/plugin/<bundler>.
• Two virtual modules with context-dependent faces: virtual:styleframe resolves to the global-instance factory when imported from *.styleframe.ts extension files, but to compiled recipe functions/selector constants when imported from app code. virtual:styleframe.css is the compiled stylesheet. Bugs that "make no sense" here are usually a face served to the wrong importer.
• HMR uses importree-based cache invalidation (importree v2): edits to any *.styleframe.ts must invalidate the virtual modules while preserving component state where possible. Test HMR changes against a live dev server — production builds cannot catch HMR regressions.
• Recipe-level tree-shaking exists (unused recipes drop from output); when touching codegen or the plugin, verify both that used recipes survive and unused ones disappear.
• A fix for one bundler is a question about eight others: state in the PR which adapters are affected and how you know the others are not.

CLI (tooling/cli) — commander-based

• Commands: init (scaffold config, tsconfig includes, detect + wire Vite/Nuxt, install deps), build, dtcg export / dtcg import, figma (generate Styleframe code from Figma export).
• Error messages are UI: every failure path says what went wrong and what to do next. A stack trace reaching the user is a bug.
• The CLI is the top-of-funnel (pnpx styleframe init is the first thing every new user runs) — treat init-flow regressions as P0.

Token interchange

• tooling/dtcg — standalone W3C DTCG library (alias resolution, classification, color/dimension/duration parsing, composite types, inheritance, guards). Heavily tested (23 test files); keep it spec-conformant — it is what makes Styleframe interoperable with Style Dictionary and Tokens Studio.
• tooling/figma — bidirectional Figma Variables ↔ DTCG ↔ Styleframe. Name mapping across three conventions (dot / slash / CSS var), multi-mode themes preserved as Figma modes. Preserve token relationships (aliases), not just values, in both directions.

Packaging traps (these broke CI once already)

• tsdown-built packages need fixedExtension: false or output silently flips .js→.mjs / .d.ts→.d.mts, breaking bin and exports targets.
• platform: "node" entries default to .mjs — same failure. After any build-config change: build, then verify every package.json exports/bin path exists in dist/.
• Known gap (verified 2026-07-11): @styleframe/plugin exports a bun adapter, but the styleframe barrel does not re-export it (engine/styleframe/src/plugin/ has no bun.ts, no ./plugin/bun export) — so the sanctioned import path styleframe/plugin/bun fails. When adding any adapter, wire it through both packages.

Release train

• Changesets: pnpm ci:changeset (author), CI runs ci:version (version PR: changeset version + lockfile refresh) and ci:publish (build:nodocs then publish). Publishable: engine/*, theme, tooling/*. Private: apps, testing, config.
• Every behavior change in a publishable package carries a changeset in the same PR — nudge authors in review when missing.
• Release notes get @mise approval before publish; anything commercial (license, Pro) also goes to Alex.

CI and deploy

• CI: build/test/typecheck/lint on PRs; actionlint gates workflow edits (lint-staged pre-commit + pnpm lint:actions); codecov patch coverage gates all packages.
• Deploys (Dokploy): apps/docs via Dockerfile — Nuxt node-server preset, filtered install, 4GB heap for prerender, sqlite content DB shipped inside .output/server, NUXT_PUBLIC_* as build args. apps/storybook — static build behind nginx, full install + turbo build of workspace deps. apps/playground + docs/storybook also carry nixpacks configs. Deploy config changes are build(deploy): commits.