Skip to content
Recursica

Variables

Variables are the control panel for the whole system: change one value and everything that reads it updates everywhere.

Early versions of Recursica managed these variables directly in Figma. That approach had real problems: Figma’s variable editor gets slow and error-prone at design-system scale, values drifted between files, and every change needed a designer with edit access to the right library. That is why Theme Forge exists. Variables are now authored, validated, and versioned in Forge, and everything else, including the Figma kit, consumes them.

Global versus component variables

Variables come in two kinds, and knowing which one you are editing tells you how far the change will travel.

Global variables are system-wide decisions: palettes and their tones, the type scale, spacing and radii, elevations, and the per-layer surface, border, and text roles. They live in the tokens and brand files. Editing one is a broad stroke, since everything downstream resolves through it.

Component variables are one component’s properties: a button’s radius at each size, a checkbox’s border in each state, a modal’s padding. They live in the ui-kit file, one entry per variant, size, and state. Editing one is a narrow, deliberate exception, and it stays consistent because it still names a global rather than a raw value.

The practical rule: change a global when the decision is about the system, a component variable when the decision is genuinely about that component. Reaching for a component variable to fix something that is really a system-wide problem is how design systems drift.

The reference chain

Neither kind holds a raw value if it can point at one instead:

component variable  →  global variable  →  primitive
ui-kit/components/button/…/border-radius
  → {brand.dimensions.border-radii.xl}
    → {tokens.sizes.3x}
      → 28px

Only the primitive at the end is a literal. That is why re-theming works without touching components, and why a wrong value can always be traced to exactly one link in the chain. Architecture walks through the files this chain spans.

Where variables are managed now

Theme Forge is the source of truth for every token in the system: color palettes, type scales, dimensions, radii, elevations, and component properties.

Definitions follow the W3C Design Tokens Community Group format, so an export from Forge is a standard, portable artifact rather than a Recursica-only file:

  • DTCG JSON for tooling, pipelines, and re-import.
  • CSS custom properties for direct use in applications.

Forge validates as you edit, including checking on-tone contrast against WCAG AA, so a bad combination is caught at authoring time instead of in review.

Getting variables into Figma

Because a Forge export is standard DTCG, it imports into Figma as native Figma variables rather than living in a Recursica-only format. The kit ships with those variables wired into every component, and you can still flip global switches inside Figma.

The direction matters: variables are managed in Forge and imported into Figma, not the other way around. Figma is a consumer of the system, the same as the code adapters are. That is what keeps a mockup and a built screen resolving the same values.

Choosing icon styles globally

To toggle every icon in your mockups between outlined and solid states:

  1. Open the Local Variables panel in the Figma UI kit file.
  2. Locate the variable named global-icon.
  3. Change the value from outline to solid. All component instances in the file will update automatically.

Customizing form components

Form overrides are grouped under the global-form variables collection. For example, to adjust the border-radius of every input field in your file:

  1. Open the Variables panel and navigate to global/form/field/size/border-radius.
  2. Change this variable to your desired token dimension.
  3. Every input, select, and textarea component will update immediately.

Keeping Figma in sync

Treat in-Figma variable edits as previews, not decisions. When a change should become part of the system, make it in Theme Forge and re-export, then re-import, so code and design read the same values from the same source. An edit that only exists in a Figma file is a value that will not survive the next export.