7ee621ec41
* feat(core): read and write W3C design tokens Variables export as DTCG 2025.10 token files, one per collection mode in the shape Figma imports, with text and effect styles as typography and shadow tokens and a resolver document that combines them. OpenPencil's own token fields ride in a dev.openpencil extension, so an export reads back as it was. Import reads plain mode files, resolver documents, and Tokens Studio themes, plans what it would add, update, or skip against the document without changing it, and applies the plan as one undo step: values merge into variables by name, nothing is deleted, and an updated style updates the layers that use it. * feat: import and export design tokens from the variables dialog The stylesheet menu exports the document's variables and styles as a zip of W3C design tokens, and Import design tokens reads token files, folders, or a zip into a dialog that shows where each collection and mode goes, what would be added, updated, or skipped and why, before applying it as one undo step. * feat: import and export design tokens from tools and the CLI openpencil tokens --format dtcg --out <folder> writes the token files, design_to_tokens takes the same format, and import_design_tokens imports token files into a document for AI, MCP, and openpencil tool call. The editor and these paths share one apply step behind a target interface: the editor makes each change undoable, a headless document takes them directly. Re-importing an export changes nothing it does not need to: values that match are left alone, layers that use an updated style are changed only outside instances, where they follow their component, and collections that share a name keep their own files apart. * perf(core): index token lookups when planning an import Resolving each reference scanned every token and variable, which made importing a large design system quadratic. A resolver now also finds files picked without their folders by name. * docs: document design token import and export * test: type the design token result in the tokens command test * fix: lay out the design token import dialog as a mapping list Each collection and mode sits beside the picker for where it goes, in one bordered list, so the pickers no longer read as headings. Skipped tokens use AppCollapsible, file problems AppAlert, and the counts move to the footer. * fix: keep durations, variable metadata, and style edits through design token import A duration Figma's format writes in seconds goes back into a variable that holds milliseconds. Tokens without OpenPencil's extension leave an updated variable's unit, scopes, and code syntax as they are. A style token whose value was edited in another tool takes that edit instead of the stale exact fields its extension still carries. Aliases to a repeated collection name resolve within one collection, a collection named Styles no longer collides with the resolver's styles set, and the dialog plans again when the document changes and right before applying. The editor imports the apply step directly rather than the whole format barrel. * fix: keep effect order and explicit alias targets in design token import Edited shadows take the places of the shadows they replace, so blurs keep their positions. An alias whose Figma data names a collection that is left out or absent is missing rather than bound to the same path in another collection. The resolver reserves the Styles set name only when there is a styles file. * perf(cli): print token stylesheets without loading every page A CSS or Tailwind stylesheet reads only variables, which load with the document, so tokens skips populating and laying out every page as variables already does. On an 85 MB design kit this takes the command from about seven minutes to seconds.
13 KiB
| title | description |
|---|---|
| Exporting | Export document content to images, PDF, PowerPoint, `.fig`, JSX, HTML, or Storybook stories, with font-substitution policies for raster and PDF output. |
Exporting
Export designs from the terminal — raster images, vectors, PDF, editable PowerPoint, .fig subsets, JSX code, HTML, or Storybook stories.
Image Export
openpencil export design.fig # PNG (default)
openpencil export design.fig -f jpg -s 2 -q 90 # JPG at 2×, quality 90
openpencil export design.fig -f webp -s 3 # WEBP at 3×
openpencil export design.fig -f svg # SVG vector
openpencil export design.fig -f pdf # PDF
openpencil export design.fig -f pptx # editable PowerPoint
openpencil export design.fig -f fig --page "Page 1" # export one page as .fig
openpencil export design.fig -f fig --node 1:23 # export one node as .fig
openpencil export design.fig -f html --css tailwind # export an HTML fragment with Tailwind classes
Options:
-f— format:png,jpg,webp,svg,pdf,pptx,jsx,html,fig,storybook-s— export scale (default:1)-q— quality:0–100(JPG/WEBP only)-o— output path--page— page name--node— specific node ID
Font Substitution Policy
For file-backed PNG, JPG, WEBP, and PDF exports, choose how missing or substituted fonts are handled:
openpencil export design.fig -f pdf --font-policy strict
openpencil export design.fig -f png --font-policy warn
openpencil export design.fig -f webp --font-policy allow
warn(default) — report substitutions and continue exporting.strict— stop with a nonzero exit status if font preparation cannot faithfully resolve the requested faces.allow— export without the additional font-fidelity check.
Run openpencil fonts first to inspect affected faces. Export preparation may use configured font providers, so its result can differ from the offline file diagnostic.
This policy does not apply to exports from the running app, or to SVG, PowerPoint, JSX, HTML, and .fig output. It checks font resolution, not complete visual equivalence with Figma.
JSX Export
Export as JSX with Tailwind utility classes:
openpencil export design.fig -f tailwind-jsx # or: -f jsx --style tailwind
Output:
<div className="flex flex-col gap-4 p-6 bg-white rounded-xl">
<p className="text-2xl font-bold text-[#1D1B20]">Card Title</p>
<p className="text-sm text-[#49454F]">Description text</p>
</div>
Also supports --style openpencil for the native JSX format (see JSX Renderer).
HTML Export
Export as an HTML fragment with inline styles by default, or Tailwind utility classes:
openpencil export design.fig -f html
openpencil export design.fig -f html --css tailwind
Use --html standalone for a browser-openable HTML document with reset styles and a page wrapper. Standalone HTML is intended as a useful visual/code handoff, not a pixel-perfect renderer replacement:
openpencil export design.fig -f html --html standalone --css inline
openpencil export design.fig -f html --html standalone --css tailwind
openpencil export design.fig -f html --html standalone --css tailwind --assets external
Standalone Tailwind output is compiled during export; it does not depend on the Tailwind browser runtime. Use --assets external to write CSS and extracted image assets next to the HTML file. Use --fonts assets with external assets to resolve detected SceneGraph text fonts through OpenPencil's configured web-font providers and emit local @font-face files.
HTML export is available in file mode.
Tokens in exported code
HTML and Tailwind JSX write variable-bound properties as the design tokens they come from: a fill bound to Primary is background-color: var(--color-primary), and in Tailwind bg-primary, or bg-(--name) for a token outside Tailwind's namespaces. A layer set to another mode gets that mode's attribute, such as data-theme="dark", so the tokens resolve as the canvas draws them.
A value stays literal where CSS would not reproduce it: the layer no longer draws the variable's value, the token is unitless where a length is needed, or the layer sits in a mode that only its own condition, such as a @media query, can select. Standalone HTML includes the stylesheet for the tokens it uses; for fragments and JSX, generate it with openpencil tokens (below).
Design Tokens
Write the document's variables as CSS custom properties:
openpencil tokens design.fig > tokens.css
openpencil tokens design.fig --format tailwind > theme.css
openpencil tokens design.fig --collection Theme --type COLOR
Each collection's default mode goes in :root. Every other mode overrides the values that differ under its condition: [data-theme="dark"] for a Theme collection's Dark mode, or the selector or @media query the mode names. Aliases stay var() references and are declared again in each mode that changes what they point to, so switching data-theme on any element restyles everything built on it.
:root {
--color-blue-500: #3B82F5;
--color-primary: var(--color-blue-500);
}
/* Theme: Dark */
[data-theme="dark"] {
--color-primary: var(--color-blue-300);
}
--format tailwind puts tokens with a Tailwind v4 namespace (--color-*, --spacing-*, --radius-*, --text-*, …) in @theme, so bg-primary and rounded-card work, and adds a @custom-variant per mode, so dark:bg-surface follows the same condition. Import the file after @import "tailwindcss";. Names come from the variable's code syntax when it names a custom property (--x or var(--x)), otherwise from its name and type: Blue/500 as a color is --color-blue-500.
Tokens that cannot be written, such as boolean variables or a condition that is not a selector or query, are listed on stderr and left out. The command works in file mode and against the running app.
W3C design tokens
--format dtcg writes the variables and styles as W3C design tokens into a folder:
openpencil tokens design.fig --format dtcg --out tokens
Each collection mode is one file, Theme/Light.tokens.json and Theme/Dark.tokens.json, in the shape Figma imports as a mode: lengths in px, times in s, booleans as numbers marked com.figma.type, and aliases to another collection naming it in com.figma.aliasData. Text and effect styles become typography and shadow tokens in styles.tokens.json, kept apart because Figma's import refuses composite tokens. tokens.resolver.json is a DTCG resolver that switches each collection's modes and layers the rest, for tools such as Style Dictionary. OpenPencil's own fields, such as a token's rem unit, CSS name, scopes, or clamp() expression, and each mode's condition, ride in $extensions["dev.openpencil"], so the export reads back exactly.
Import token files into a document with the import_design_tokens tool, passing each file's path and text:
openpencil tool call import_design_tokens design.fig --args-file tokens.json --write
It reads a file per mode grouped by folder, a resolver with the files it refers to, or a Tokens Studio file with $themes. Collections and modes with existing names, and variables and styles by name, are updated; the rest is added, and nothing is deleted. The result lists what was added, updated, and skipped, with the reason for each skip.
Storybook Export
Generate one CSF3 .stories.ts file per component set or component:
openpencil export design.fig -f storybook # React stories in ./design-stories/
openpencil export design.fig -f storybook --framework vue -o src/stories
openpencil export design.fig -f storybook --framework html --page "Components"
openpencil export design.pen -f storybook -o src/stories --watch # re-export on every save
openpencil export 'src/**/*.pen' -f storybook --beside --watch # stories next to each design
Designs next to their stories
Keep each component's design file in the component's folder and export with --beside: each document's stories, design images, and .openpencil-stories.json manifest go into that document's own folder, next to the component's code. A Storybook stories glob such as ../src/**/*.stories.ts in .storybook/main.ts then picks them up without further configuration.
Pass several documents, or a quoted glob such as 'src/**/*.pen' that OpenPencil expands itself (Node.js 22 or later). Several documents need --beside or --output; --page works with one document only. Documents are exported one after another, and when one fails the rest are still exported before the command exits with an error. --watch watches every matched document; a document created after the watch started needs another run.
Each variant of a component set becomes a story, and its variant properties become select controls, so switching a control shows the matching variant. A set with a behaviour gets the control's own props instead: a Switch or Checkbox has a checked boolean, a Toggle pressed, a Collapsible open, and disabled when the set draws a disabled state; hover, pressed, and focus stay stories of their own. Standalone components named with slashes, such as Button/Primary and Button/Secondary, are grouped into one Button file with a Variant control. A combination the design has no variant for throws a named error in Storybook rather than showing a different variant.
Stories render the component as HTML with inline styles, like -f html, so they need no OpenPencil runtime; --framework (react, vue, or html) only changes the wrapper and the Meta/StoryObj import from @storybook/react-vite, @storybook/vue3-vite, or @storybook/html-vite. Text uses the document's font families, which Storybook has to load itself. Text, boolean, and instance-swap properties are not exported yet.
With --framework vue or --framework react, a component set whose behaviour is a Button, Switch, Checkbox, Toggle, or Collapsible becomes a real component instead: <Name>.vue built on Reka UI, or <Name>.tsx with a <Name>.module.css built on Radix UI's radix-ui package. Its variants are compiled into a stylesheet keyed on the states Reka and Radix set (data-state, data-disabled, hover, and focus), and every other variant property is a prop the component sets as a data-* attribute. In Vue its value is a v-model such as checked or open; in React the component takes the Radix root's props, such as checked, defaultChecked, and onCheckedChange. Its stories render the component, and a play function clicks the control and checks its state, so the Storybook project needs reka-ui or radix-ui installed.
Stories carry parameters.design entries for @storybook/addon-designs:
- OpenPencil — when the document path is inside the current directory, an
openpencil://link that opens the document in the desktop app and selects the variant, or its component set when another layer shares the variant's name. The scheme addresses layers by name, so a story whose variant and component names are both shared by other layers gets no link. - Design — a 2× PNG of the variant, written to
<Name>.design/next to the story and referenced withnew URL(…, import.meta.url), so Vite bundles it. Copy the parameter onto the story of your own component to compare the implementation with the design.--no-design-imagesskips rendering; font substitution follows--font-policyas in raster export.
-o names the output directory. A .openpencil-stories.json manifest there records which document, as a path relative to the output directory, and which page generated each story and design image; commit it with the stories. An export replaces the files that a previous export of the same document generated there, including those of components since deleted or renamed; with --page, only that page's. It refuses, before changing anything, to overwrite any other file — a hand-written story, another document's, or a stray image. A one-page export whose file names shifted onto another page's stories asks for a full export instead. Without the manifest, existing stories count as someone else's, so remove them before exporting again. --watch keeps the command running and re-exports whenever the document is saved, so Storybook's hot reload follows the design; a save that cannot be read is reported and the watch continues. A missing --page or a --font-policy strict substitution still ends the command.
Live App Mode
Omit the file to export from the running app:
openpencil export -f png # export the selection in the active document
openpencil export --page "Components" -f png # export every layer of a page
openpencil export --node 1:23 -f png # export one layer, on any page
--page takes a page name and --page-id a page ID from openpencil documents list; either exports that page without switching the app to it. Add --document-id to export from a document other than the active one.
Live app mode supports PNG, JPG, WEBP, SVG, and PDF. PowerPoint, JSX, HTML, Storybook, and .fig exports require a file argument. File-mode thumbnail export is not currently supported.