Skip to main content

N2-03 · The Config-First Paradigm

Context​

In most design systems, Figma is the starting point. The designer chooses colors, defines styles, organizes the library. The developer then translates those decisions into code.

In Aplica DS, the flow is inverted. This tutorial explains why that inversion exists, what it changes in practice, and which decisions still belong to Figma.

Concept​

The problem with Figma as the source of truth​

When Figma is the source of truth, there is a structural problem: any decision made in Figma must be manually translated to every other context — code, mobile, email, documentation.

If the primary color changes in Figma, someone needs to update the code. If the code is updated without going through Figma, Figma falls out of date. Which is correct? The honest answer is: nobody knows for sure.

Moreover, Figma knows nothing about dark mode, multi-platform, or multi-brand. You can have a manually created dark version, a mobile version that is an independent copy, and tokens that have silently diverged over months.

The inversion: code as the source of truth​

In the Config-First paradigm, the design decision starts in the theme configuration file (*.config.mjs). There you declare:

  • Brand colors (one hex per semantic role)
  • Typography (font families and weights)
  • Pipeline options (txtOn strategy, dark mode saturation)

The engine reads that file and automatically generates:

  • All layers (Brand → Mode → Surface → Semantic → Foundation)
  • All output formats (CSS, JSON for Figma, JS modules, TypeScript)
  • All themes (light/dark × positive/negative)

Figma receives the tokens via JSON — it does not create the tokens. It consumes them.

What this changes in practice​

Before (Figma as source)After (Config-First)
Designer chooses colors in FigmaDesigner declares the color in the config
Dev "translates" Figma to codeDev loads the CSS generated by the engine
Dark mode created manuallyDark mode generated by the pipeline
Multiple brands = multiple FigmasMultiple brands = multiple configs
Gradual inconsistency guaranteedMathematical consistency guaranteed

What Figma still decides​

The inversion does not mean Figma loses relevance. It is still the right space for:

  • Composition and layout — how components are organized on screen
  • Visual hierarchy — which elements are more prominent
  • Flow and navigation — the sequence of screens and states
  • Prototyping — simulating interaction before implementation
  • Component specification — documenting the behavior of new components

Figma is the space for compositional decisions. The config is the space for visual identity decisions.

Guided example​

Simulating a brand color change​

Imagine the client decides to change the primary action color from #C40145 to #D01050.

In the old paradigm:

  1. Designer opens Figma, changes the color style
  2. Exports a report of affected components
  3. Dev updates the variable in CSS
  4. Dev updates the variable in React Native
  5. Dev updates the token in the email JSON
  6. Someone checks dark mode (probably forgets)
  7. Weeks later: some product still has the old color

In the Config-First paradigm:

  1. System Designer opens *.config.mjs and changes the hex for action_primary
  2. Runs npm run build:themes
  3. Figma receives the new JSONs and updates automatically
  4. CSS, ESM, CJS, and TypeScript are generated with the new values
  5. Dark mode, multi-brand, mobile — everything regenerated

One change, one place, all consequences calculated.

The complete cycle of a design decision​

1. DECISION
   System Designer declares in config:
   "The primary action color for this brand is #D01050"

2. GENERATION
   npm run build:themes
   Engine generates: full palette, dark mode, neutrals, all formats

3. DISTRIBUTION
   JSON → Figma (via Tokens Studio)
   CSS  → Web
   ESM  → React / Vue
   CJS  → Node.js
   JSON → Documentation

4. CONSUMPTION
   Figma: designer applies tokens to components
   Web:   dev uses var(--semantic-color-*)
   Mobile: dev uses values from ESM

5. VALIDATION
   Product Designer verifies in Figma
   Engineer verifies in browser
   If something needs to change → back to step 1

Now you try​

Identify, for each decision below, where it should be made in the Config-First paradigm:

  1. The "Save" button color is too dark — needs to be lighter
  2. The spacing between home cards is too tight
  3. A new product wants to use green as its brand color
  4. The error alert needs a more intense red tone (secondary)
  5. The page title has the wrong font
  6. It was discovered that the badge component's dark mode has a hardcoded hex

Expected result:

DecisionWhere to resolve
Button too darkConfig (txtOnStrategy or color mapping) — it is an identity decision
Tight spacingFigma (composition) → if persistent, config (Dimension scale)
New green brand colorConfig — new *.config.mjs for the new product
More intense red toneConfig — adjust the hex for danger_secondary
Wrong title fontConfig — typography.fontFamilies.main
Hardcoded hex in badgeComponent code — refactor to use Semantic token

Checkpoint​

By the end of this tutorial you should know:

  • Why Figma as the source of truth creates synchronization problems
  • What Config-First means: the config is the origin, Figma is the consumer
  • The complete cycle: declaration in config → build → distribution → consumption
  • Which decisions still belong to Figma (composition, flow, prototyping)
  • How to trace a color change from config to Figma

Next step​

N2-05 · Product colors — responsible growth

You understand the paradigm and the pipeline. The next step is to learn about the most dangerous area of the system: product colors. Why does each new product color cost much more than it seems?

References​