AI-native design editor. Open-source Figma alternative.
OpenPencil design authoring
This reference describes scene creation, not React DOM output. Use the render tool for JSX strings, or import Frame, Text, and other authoring exports from @open-pencil/design-jsx and render them with renderTree from @open-pencil/core/design-jsx in library code. Library exports are not automatically globals in agent eval; use only the bindings exposed by that execution environment.
Composition and layout
flex="row"/flex="col"enables auto-layout. Use it for content; reserve explicitx/yorposition="absolute"for intentional overlays and artwork. Without layout, children share the origin unless positioned.w/haccept pixels,"hug"(content-sized), or"fill"(available space in a supported layout parent). Use Hug for notes, cards, and long pages instead of guessing heights. Fixed viewport sizes and artwork geometry are intentional exceptions.gapcontrols spacing.p,px,py, andpt/pr/pb/plcontrol padding; longhands override shorthands. There is no margin shorthand.justify="start"|"end"|"center"|"between"controls the primary axis;items="start"|"end"|"center"|"stretch"|"baseline"controls the cross axis. Distribution needs available space:betweencannot create extra room in a Hug container.growdistributes available space. Avoid circular Hug/Fill dependencies and redundant fixed widths on growing children. Keep Fill sizing through intermediate containers that should stretch.- For wrapping text in a column, prefer
w="fill"; fixed-width text can usetextAutoResize="height".maxLines/truncateare intentional truncation, not fixes for accidental overflow. wrapandrowGapenable wrapped flex rows.grid,columns, androwsenable grid (for examplecolumns="1fr 200px 1fr"orcolumns="repeat(7, 1fr)"); tracks arefr, pixel lengths,auto,repeat(), andminmax(), which grows like its maximum. Grid children usecolStart,rowStart,colSpan, androwSpan. The current gridgapshorthand takes precedence overcolumnGapandrowGap.flow="auto"|"ltr"|"rtl"controls container flow; textdircontrols writing direction. Preserve these separately.- Outside auto-layout, and for
position="absolute"children,constraints={{ horizontal, vertical }}sets how a layer follows its parent's resizing, with Figma's values in lowercase:"min","center","max","stretch", or"scale".minW,maxW,minH, andmaxHbound a layer's size.visible={false}hides a layer andlockedlocks it. - Use measured node bounds and the existing
arrangetool for independent artboards:packfor a page of screens,spreadwhen generated layers overlap. Prefer layout constraints to calculating child coordinates; ordinary JavaScript arithmetic is appropriate when real geometry calculations are needed.
Paint, text, and artwork
bg/fill,stroke, and textcoloraccept colors and supported variable references. Set colors explicitly for predictable contrast.fillsaccepts structured paints; gradient helpers includelinearGradient,radialGradient,angularGradient, anddiamondGradient, each taking an array of stops and optional{ opacity, transform }:fills={[linearGradient([['#3b82f6', 0], ['#8b5cf6', 1]])]}. Without atransforma linear gradient runs left to right and the others are centred;transformis Figma'sgradientTransform, mapping the layer's unit square onto gradient space. Write it as the plugin API's rows, as export does:linearGradient(stops, { transform: [[0, 1, 0], [-1, 0, 1]] })runs top to bottom. A paint written as an object takes itsgradientTransformandimageTransformas rows too; the matrix fields{ m00, m01, m02, m10, m11, m12 }are accepted as well.shader(effects, { opacity, visible, blendMode })fills a layer with a shader from theshaderslibrary: an array of effects such asbg={shader([{ type: 'Aurora', props: { speed: 2 } }])}, or a preset as shaders.com exports it,{ components: [...] }. The canvas shows the shader's first frame, preview plays it, and files and other formats keep that frame as an image.strokedescribes one stroke, refined bystrokeWidth,strokeAlign("inside","center","outside"),strokeDash,strokeCap, andstrokeJoin.strokestakes several, as objects withcolor,weight,align,dash,cap,join, andvisible;strokeWeights={{ top, right, bottom, left }}sets per-side widths.dashPatternsets the node's own dash pattern, separate from the per-strokestrokeDash.roundedandroundedTL/roundedTR/roundedBL/roundedBRcontrol corners.strokeWidth,opacity,rotate, andblendModecontrol appearance.overflow="hidden"clips content; do not hide accidental text overflow to make a broken layout appear correct.rotateturns a layer by degrees, andflipXandflipYreflect it across its centre before it turns, as the canvas places it.StartakespointsandinnerRadius(0–1, how deep its points go);Polygontakespoints.Ellipsedraws an arc or a donut withstartAngleandendAnglein degrees, clockwise from three o'clock (0 to 360 by default), andinnerRadius(0–1, the hole):<Ellipse w={80} h={80} startAngle={0} endAngle={270} innerRadius={0.6} />.effectsaccepts structured effects such asdropShadow,innerShadow, andlayerBlur.shadowtakes a CSSbox-shadowlist, such asshadow="0 4 8 #0002, inset 0 1 0 #fff", andblura layer blur radius; both are convenient shorthands. Effect helpers takeradius, as Figma's effects do; when a JSX string is rendered, an option a paint or effect helper does not support is reported as a warning.- Text content belongs inside
Text. Usesize,font,weight,italic,lineHeight,letterSpacing,textAlign,textAlignVertical,textDecoration, andtextCase. Decorations take CSS's names and values:textDecorationStyle(solid,dotted,wavy),textDecorationColor(currentColorfollows the text),textDecorationThicknessandtextUnderlineOffset(pixels orauto), andtextDecorationSkipInk.fontFeaturesturns OpenType features on or off by tag (fontFeatures={{ tnum: true, liga: false }}),fontVariationssets variable-font axes by tag (fontVariations={{ wght: 650 }}), andlangnames the text's language (lang="de") for shaping and font fallback. A variable font's optical size follows the font size unlessfontOpticalSizing="none", as in CSS; only then does anopszinfontVariationsapply.lineHeight="auto"follows the font, andfills={[]}paints no text. Verify fonts actually load before judging dimensions; do not assume every font is available. Spanstyles some characters of aText, or of aSticky's body, aShape's label, or aConnector's label, withText's own prop names:size,font,weight,italic,color,fills,lineHeight,letterSpacing,textDecoration, the decoration details,fontFeatures,fontVariations,lang, andtextCase; a span'sfontFeaturesandfontVariationsreplace the text's rather than adding to them, andfontOpticalSizingis set on theTextfor all of it.hreflinks its characters to a URL without changing how they look. Spans nest; the inner one wins.Paragraphwrites one paragraph:list="ordered"orlist="unordered"makes it a list item nested atlevel1–5, andspacing,listSpacing, andindentoverride theText'sparagraphSpacing,listSpacing, andparagraphIndentfor it;hangingListon theTexthangs list markers outside the text box. ATextholds onlyParagraphs or none; without them, a line break in its text still starts a paragraph.Text markdownreads its text, children ortext, as Markdown over theText's own style, as FigJam styles typed Markdown:#and##headings bold at 2.5× and 1.5× its size, deeper ones bold at its size, all at a 150% line height;**bold**,*italic*,~~strike~~,`code`in Roboto Mono,[links](url),-and1.lists, and>quotes in italic. Write multiline Markdown as a template literal,<Text markdown>{`...`}</Text>, since JSX folds the line breaks of plain children, and escape a code span's backticks in it as\`; the indent its lines share is left out. It holds noSpanorParagraph.Iconuses an Iconify name, size, and color. Prefer icons to emoji when reliable vector output is needed. Image fills belong on appropriate leaf shapes, not containers whose children must remain visible.- Pick artwork by where it comes from. A known icon is an
Iconby its Iconify name. A shape you draw yourself is aVectorwith its path in SVG syntax,<Vector d="M11 2L4 11h5l-1 7 7-9h-5z" bg={designVar(…)} />: one layer, styled with the same props as any other, so its fills can use variables, stack, and takestrokeAlignandeffects.fillRule="evenodd"cuts holes. An open path with astrokestays open, a line; with only abgit fills as if closed. Givenwandh, the path is drawn in that box as written, as an icon is in its view box; without them the layer fits the path.pathstakes several paths as export writes them, each{ windingRule, data }withNONZERO,EVENODD, orNONEfor an open path:paths={[{ windingRule: "EVENODD", data: "M0 0L10 0L10 10Z" }]}. Inline<svg>is for artwork copied from elsewhere: it draws the SVG's shapes, a frame with a layer per shape in the SVG's own colours, and leaves out its text, so do not use it for a shape you will style or bind, nor for text. Stickymakes a FigJam sticky note whose text is its body:<Sticky color="yellow" author="Ada">Ship it</Sticky>.colortakes a FigJam palette name (white,gray,red,orange,yellow,green,teal,blue,violet,pink) or any colour,authorsigns it (authorVisible={false}hides the line),widemakes it 416 wide instead of 240,textSizeissmall,medium,large,extraLarge, orhuge,typefaceissimple,bookish,technical, orscribbled, andscalescales the whole note. A note sizes itself; it takes now,h, fills, or layout props.Shapemakes a FigJam shape with text whose text is its label:<Shape kind="diamond" bg="#FFC943">Valid?</Shape>.kindissquare(default),ellipse,diamond,rounded_rectangle,parallelogram_right,eng_database, or another FigJam shape, written in lowercase.wandhare the size it is given (176 by default); it grows taller to fit its label, never wider, so a word too long for it breaks.truncatekeeps its height and cuts the label off with "…" instead, as FigJam does once a shape's height is set.bg,stroke,strokeWidth,rounded(6 by default; arounded_rectanglekeeps its corners at 0.4 of its shorter side, as FigJam does), androtatestyle it as any layer; the label is centred in the shape and takes the sametextSizeandtypefaceasSticky.Connectordraws a FigJam connector that follows the layers it joins:<Connector from="Start" to="Done">Next</Connector>.fromandtoname layers of the same JSX, take aref()a layer is marked with (const card = ref(), then<Frame ref={card}>andfrom={card}), or give{ x, y }points in the connector's parent;fromSide/toSide(top,right,bottom,left) fix the side it attaches by,lineiselbowed(default),straight, orcurved, andstartCap/endCaptake the same caps asstrokeCap:none,round,square,arrow_lines,arrow_equilateral,triangle_filled,diamond_filled, orcircle_filled(it starts with none and ends witharrow_lines). Its text is the label;stroke,strokeWidth, anddashPatternstyle the line. When layers share a name, join them byref(); a name more than one layer has joins the first, with a warning.- Design JSX props are the portable authoring interface. Some CSS-style aliases are supported, but this is not a browser CSS engine; do not assume arbitrary HTML, classes, or styles work.
Variables and components
defineVars('Theme', { Page: '#FFFFFF', Radius: 12 }, { mode: 'Light' })defines a collection in the file's variables table and returns its variables by name, such astheme.Page. Each value is the variable's value in the first mode, named bymode(Mode 1without one): strings are colors, numbers FLOAT, booleans BOOLEAN, and another collection's variable makes an alias, such aspalette['Gray/900'].defineMode(theme, 'Dark', { Page: '#111111' })adds a mode with the values that differ; the rest keep the first mode's. A render that binds any of the variables creates the collection with all its modes, or updates the one with that name, so running the JSX again changes values instead of adding collections.designVar('name-or-id')refers to a variable the document already has; a missing one is an error. When more than one collection has a variable of that name, name the collection too, asdesignModedoes:designVar('Theme', 'Line').- COLOR references work in paint props. FLOAT references work in
w,h,gap, padding, corner radii,strokeWidth,opacity, textsize/fontSize,lineHeight, andletterSpacing. GridcolumnGap/rowGapand wrapped flexrowGapalso support FLOAT references; gridgapoverrides both axis-specific gaps. Use numbers or FLOAT references for these scalar props, not CSS unit strings; the one exception islineHeightandletterSpacing, which also take a percent of the font size such as"150%"that follows the size when it changes. mode={dark}shows a layer and its children in a mode, as the Appearance panel's variable mode control does; a list pins several collections, anddesignMode('Theme', 'Dark')names a mode of a collection the document already has, by the collection's ID when several share its name. Withoutmode, a layer inherits its parent's.- Variables bind real graph fields, not copied values. Layout resolves scalar variables in the mode the layer is created in, its own or inherited; it does not lay content out again after a later mode switch. Verify resulting geometry as well as paint when changing modes. Missing or incorrectly typed scalar variables are errors.
bindmaps supported scene-field paths to variable IDs or references when no shorthand exists. Use semantic tokens consistently rather than declaring unused collections.- Build repeated or computed content with JavaScript inside
{}rather than writing each item out:{days.map((day) => <Text>{day}</Text>)},{Array.from({ length: 35 }, (_, i) => <Frame>…</Frame>)}, and conditionals. Statements such asconst weeks = …may come first and then end withreturnand the JSX, as a component's body does:const weeks = 5on one line,return <Frame>…</Frame>on the next. - A reusable JavaScript function shares source code, not component identity. Use
Component,ComponentSet, andInstancefor editable main components and linked instances. Instanceresolves an existing component throughof,component, orcomponentId, by name or ID. When components share a name, mark the one you mean with aref()and pass it:const card = ref(), then<Component name="Card" ref={card}>and<Instance of={card} />. A swap property's default and values take aref()the same way:of={property('Icon', card)},Icon={card}. Component-set children namedvariant=Primary, for example, define variants that can be selected when instantiating the set; a value the set does not have is an error. A variant property named like a layer prop, such asvisible, keeps the prop's meaning, so select such a variant by naming it:<Instance of="visible=false" />.property(name, defaultValue)binds a field of a component's layer to a component property, created on first use:text={property('Message', 'Hi')}on aTextmakes a TEXT property,visible={property('Pinned', true)}a BOOLEAN one, andof={property('Icon', 'Star')}on anInstancean INSTANCE_SWAP one whose default is the componentofnames. The property belongs to the nearestComponent, or to itsComponentSetfor a variant, so the same name in each variant binds one property; one name with two types or two defaults is an error.- An
Instancesets text, boolean, and swap properties by name, the way it picks a variant:<Instance of="Note" State="Done" Message="Updated review" Pinned={false} />.propertiestakes the same values keyed by property ID or name, for names that are not JSX identifiers or that design JSX already uses, such asname. Only instances acceptproperties. exposedon anInstancein a component shows that instance's own properties on the component's instances, as Figma's "Expose properties from nested instances" does; the instance's component needs properties to expose. An outer instance gives an exposed instance its variant and properties as an object under the exposed layer's name:<Instance of="Card" Title="Welcome" Action={{ Variant: 'Secondary', Label: 'Save' }} />, orproperties={{ Action: { … } }}.- Instance assignments take
true/falseor the native'true'/'false'for BOOLEAN properties, and a component's name, ID, orref()for swaps, asofdoes, whether set as a prop or inproperties. Assignments persist through component synchronization; unknown IDs and invalid values fail rather than silently creating inert overrides. Select variants through component-set variant props, not through instance property assignments. - An exported
Instancehas no children: its layers are its component's. What it changes in them is inoverrides, keyed by the layer's name in the component and the scene field, with the field's value:overrides={{ 'Dot:fills': [...] }}. A name several of its layers share is an error; a key that names no layer, a field an instance cannot override, or a value of another kind is skipped with a warning. Change per-instance content through properties rather thanoverrides. An instance whose changes cannot be written that way exports as theFrameit draws. - Reuse existing local or library components before recreating them. Keep meaningful text, visibility, and swap properties exposed rather than hand-editing cloned child nodes.
- Explicit instance
w/hreplace the inherited sizing mode on that axis; omitted dimensions retain the main component's sizing. Authored overrides survive component synchronization. Distinguish those placement constraints from the main component's default size, and verify actual bounds in narrower parents. Do not compensate for a sizing mismatch with guessed heights, clipping, or manually positioned siblings.
Controls
- A main component can behave as a Reka UI control in preview and code. Write it with Reka's names:
Switch.Rootis the component (a component set when its children areComponentvariants), and each Reka part is the slot that draws it, such asSwitch.Thumb,Slider.Track,Slider.Range,Slider.Thumb,Progress.Track,Progress.Indicator,Tabs.List,Collapsible.Trigger, orNumberField.Increment. Parts in different variants share one slot. - The root names the properties that hold its values:
modelValue(openonCollapsible.Root),disabled, for form controls (fields, switches, checkboxes, radios)invalid, and, for text fields,filled, as a variant or boolean property name, or{ property, on, off }when the variant values are not named like On and Off.statesnames the variant property that draws default, hover, pressed, focus, disabled, and, for form controls, invalid (a value named Invalid or Error); a slider, progress bar, or number field takesmin,max,step, anddefaultValue. TextField.Input,Textarea.Input, andNumberField.Inputare the text layers whose text becomes the field's text property.Tabs.Triggergoes inTabs.List;Tabs.Contentpanels may sit directly underTabs.Root, the first showing. A part with children and noflex,display,w, orhof its own stacks them in a column that hugs them.- A group's item component is written on its own (
RadioGroup.Item,ToggleGroup.Item,Accordion.Itemwith itsAccordion.TriggerandAccordion.Content); the group's root then lists items as<RadioGroup.Item of={radioId} />. - A tab trigger with a selected look of its own is a
Tabs.Tabcomponent, written on its own withmodelValuenaming its selected variant property;Tabs.Rootthen lists its tabs as<Tabs.Tab of={tabId} />, which go in the list as plainTabs.Triggers do, and each shows its selected variant while its tab is chosen.
<Switch.Root name="Switch" modelValue="State" states="Interaction">
<Component name="State=Off, Interaction=Default" w={44} h={24} rounded={12} bg="#D0D4DA">
<Switch.Thumb x={2} y={2} w={20} h={20} rounded={10} bg="#FFFFFF" />
</Component>
<Component name="State=On, Interaction=Default" w={44} h={24} rounded={12} bg="#3B6CF6">
<Switch.Thumb x={22} y={2} w={20} h={20} rounded={10} bg="#FFFFFF" />
</Component>
</Switch.Root>
Verification
Inspect structure and actual rendered output. Node counts and describe diagnostics do not establish visual fidelity. Check wrapping with longer content, narrower containers, component edits, and relevant modes. Resolve overflow and contrast problems at their source. Reuse IDs returned by creation tools rather than repeatedly searching for the same nodes.
The examples below are executed by the authoring-reference tests. Create the named variables before running a variable-bound example.
Content-sized review note
<Frame name="Review note" w={280} h="hug" flex="col" gap={8} p={16} bg="#FFFFFF">
<Text name="Author" size={12} weight="medium" color="#252A31">June Lee</Text>
<Text name="Message" w="fill" size={12} color="#6B7079">Give the date a little more room at the bottom.</Text>
</Frame>
Variable-bound spacing and typography
<Frame name="Bound note" w={280} h="hug" flex="col" gap={designVar('Space/small')} p={designVar('Space/medium')} bg="#FFFFFF">
<Text name="Message" w="fill" size={designVar('Type/body')} lineHeight={designVar('Type/body-leading')} letterSpacing={designVar('Type/body-tracking')} color="#252A31">A note that grows with its content.</Text>
</Frame>
A theme with two modes
const theme = defineVars('Theme', { Surface: '#FFFFFF', Ink: '#252A31', Radius: 12 }, { mode: 'Light' })
const dark = defineMode(theme, 'Dark', { Surface: '#1A1A20', Ink: '#F5F5F7' })
return <Frame name="Dark note" mode={dark} w={280} h="hug" flex="col" gap={8} p={16} bg={theme.Surface} rounded={theme.Radius}>
<Text name="Message" w="fill" size={12} color={theme.Ink}>Shown in the Dark mode of the Theme collection.</Text>
</Frame>
Component with text and visibility properties
<Component name="Comment" w={280} h="hug" flex="col" gap={8} p={16} bg="#FFFFFF">
<Text name="Author" size={12} weight="medium" color="#252A31" text={property('Author', 'June Lee')} />
<Text name="Message" w="fill" size={12} color="#6B7079" text={property('Message', 'Give the date more room.')} visible={property('Show message', true)} />
</Component>
Rich text with spans and lists
<Frame name="Release notes" w={280} h="hug" flex="col" gap={8} p={16} bg="#FFFFFF">
<Text name="Notes" w="fill" size={12} color="#252A31" paragraphSpacing={4}>
<Paragraph spacing={8}>Version 2 is <Span weight="bold" color="#3B6CF6" textDecoration="underline" textDecorationStyle="wavy" textUnderlineOffset={2}>out now</Span>.</Paragraph>
<Paragraph list="unordered">Faster export</Paragraph>
<Paragraph list="unordered" level={2}>PDF and SVG</Paragraph>
<Paragraph list="ordered">Fewer clicks</Paragraph>
</Text>
</Frame>
Supported syntax inventory
Generated from the renderer metadata. This inventory lists accepted names, not arbitrary browser CSS support.
Elements: Frame, Text, Span, Paragraph, Rectangle, Ellipse, Line, Star, Polygon, Vector, Group, Section, Component, ComponentSet, Instance, View, Rect, Icon, Sticky, Shape, Connector, Button.Root, Toggle.Root, Switch.Root, Switch.Thumb, Checkbox.Root, Checkbox.Indicator, RadioGroup.Root, RadioGroup.Item, RadioGroup.Indicator, ToggleGroup.Root, ToggleGroup.Item, Slider.Root, Slider.Track, Slider.Range, Slider.Thumb, Progress.Root, Progress.Track, Progress.Indicator, Tabs.Root, Tabs.List, Tabs.Trigger, Tabs.Tab, Tabs.Content, Collapsible.Root, Collapsible.Trigger, Collapsible.Content, Accordion.Root, Accordion.Item, Accordion.Header, Accordion.Trigger, Accordion.Content, NumberField.Root, NumberField.Input, NumberField.Increment, NumberField.Decrement, TextField.Root, TextField.Input, Textarea.Root, Textarea.Input.
Helpers: solid, gradient, linearGradient, radialGradient, angularGradient, diamondGradient, shader, dropShadow, innerShadow, layerBlur, backgroundBlur, foregroundBlur, defineVars, defineMode, designVar, designMode, property, ref.
Properties: name, key, ref, flex, flow, dir, gap, wrap, rowGap, columnGap, justify, justifyContent, items, align, alignItems, grow, w, h, width, height, minW, maxW, minH, maxH, x, y, top, left, position, constraints, p, padding, px, py, pt, pr, pb, pl, bg, fill, fills, background, backgroundColor, stroke, border, borderColor, strokeWidth, borderWidth, strokeAlign, strokeDash, strokeCap, strokeJoin, dashPattern, strokes, strokeWeights, rounded, borderRadius, roundedTL, roundedTR, roundedBL, roundedBR, cornerRadius, cornerSmoothing, opacity, blendMode, rotate, rotation, flipX, flipY, overflow, mask, visible, locked, shadow, blur, effects, size, fontSize, font, fontFamily, weight, fontWeight, italic, color, text, characters, content, value, title, markdown, textAlign, textAlignHorizontal, textHorizontalAlignment, textAlignVertical, textVerticalAlignment, textAutoResize, lineHeight, letterSpacing, textDecoration, textDecorationStyle, textDecorationColor, textDecorationThickness, textUnderlineOffset, textDecorationSkipInk, fontFeatures, fontVariations, lang, fontOpticalSizing, textCase, paragraphSpacing, paragraphIndent, hangingList, list, level, spacing, listSpacing, indent, maxLines, truncate, grid, columns, rows, colStart, rowStart, col, row, colSpan, rowSpan, points, pointCount, innerRadius, startAngle, endAngle, d, fillRule, paths, label, style, bind, component, componentId, properties, of, exposed, overrides, mode, modelValue, open, disabled, invalid, filled, states, min, max, step, defaultValue.