Skip to main content

N2-06 · Responsible Overrides

Context​

The Aplica DS pipeline is sophisticated — but it is not omniscient. There will be cases where the generated behavior is not exactly what a brand needs. The neutral tone came out too cold. The generated gray does not match the warm identity of the brand.

Overrides exist for those cases. But they have a cost — not in tokens, but in maintainability — and a protocol that must be followed.

Concept​

What overrides are​

Overrides are configurations in *.config.mjs that replace values generated by the default pipeline. You are telling the engine: "For this specific case, ignore the calculated value and use this one instead."

The engine accepts overrides at two points:

1. Grayscale — the fixed gray scale
By default, grayscale is a neutral gray. Brands with warm identities (fashion, food, lifestyle brands) often need slightly yellowed or pinkish grays to maintain visual coherence.

overrides: {
  grayscale: {
    light: {
      surface: {
        '5':   '#faf8f5',  // off-white with warm tone
        '10':  '#f5f2ee',
        '140': '#1a1814'   // near-black with warm tone
      }
    },
    dark: { /* same structure */ }
  }
}

2. Neutrals — the grays derived from the brand color
By default, neutrals are calculated with 10% of the brand color's chroma. Sometimes that calculation does not produce the desired visual result.

overrides: {
  neutrals: {
    brand_primary: {
      light: { surface: { '5': '#fdf4f9' } }  // only the level that needs it
    }
  }
}

The mandatory cycle: Study → Test → Document​

Before applying any override, follow these three steps:

Study: Why does the default value not work? Is the problem real or an aesthetic preference? Sometimes what seems wrong is correct for WCAG and the problem lies in another layer.

Test: Apply the override in an isolated environment. Check behavior in both light and dark mode. Confirm that contrast is still adequate in all contexts where the value is used.

Document: Record in the config (via comment) or in the theme's CHANGELOG: what the problem was, what the solution was, when it was applied. Undocumented overrides become impossible mysteries to solve months later.

What to NEVER override​

Semantic tokens directly. The Semantic layer is generated by sync:architecture — any manual edit to data/semantic/default.json is overwritten on the next execution. If you need to change the behavior of a Semantic token, the change must happen in the schema or in the theme config, not in the generated file.

Calculated txtOn values. txtOn is calculated to guarantee WCAG AA. Overriding it manually to "look better visually" removes the accessibility guarantee. If you need a different strategy, use txtOnStrategy: 'brand-tint' or 'custom-tint' in the config — do not override txtOn directly.

Guided example​

Three scenarios: correct, unnecessary, and problematic overrides​

Scenario A — Legitimate override

Artisan food brand. Warm, rustic identity. The default grayscale (cold gray) clashes visually with the entire palette.

Solution:

overrides: {
  grayscale: {
    light: {
      surface: {
        '5':   '#faf9f7',   // slightly yellowed white
        '10':  '#f5f3f0',
        '20':  '#ebe8e3',
        '140': '#1f1d1a'    // slightly brownish black
      }
    }
  }
}

Documentation in config:

// Grayscale override: brand's warm identity requires grays with
// 2-3% yellow/orange tone. Approved by: DS team, 2026-03.

Scenario B — Unnecessary override

A designer found that level 50 of the primary palette "looked different from what they expected in Figma." They want to override the level 50 surface.

Analysis:

  • The hex generated by the OKLCh pipeline may be slightly different from the declared hex — this is expected and correct.
  • If the contrast is correct and the palette is harmonious, a 1-2 digit difference in the hex is not a problem.
  • Overriding to "match Figma" will create a level that departs from the lightness curve of the entire palette.

Decision: Do not apply the override. Update Figma to accept the generated value as canonical.

Scenario C — Problematic override

An engineer wants the txtOn for level 100 of the primary color to always be black (to maintain the brand style) even when white has more contrast.

Analysis:

  • txtOn guarantees WCAG AA. Forcing black over a dark background can fail contrast.
  • If the brand wants to maintain color identity in text, the solution is txtOnStrategy: 'brand-tint' — the engine will choose the brand tone that passes WCAG.

Decision: Use txtOnStrategy: 'brand-tint' instead of a manual override. Document if it still does not meet expectations.

Now you try​

Given the scenario below, decide whether an override is necessary and, if so, which one is correct:

Personal finance brand. Primary palette: blue #2563EB. The automatically generated neutral has a very noticeable blue tint — in a finance app, where trust is visual, the near-blue neutral looks "not serious enough." The branding team wants neutrals closer to pure gray.

Expected result:

Legitimate override. The 10% chroma applied to the vibrant blue results in a neutral with a bluer appearance than desired for a serious finance brand.

Solution:

overrides: {
  neutrals: {
    brand_primary: {  // key matching the #2563EB hex in the config
      light: {
        surface: {
          '5':   '#f8f9fa',  // near-pure gray
          '20':  '#e8eaed',
          '60':  '#9aa0a6',
          '100': '#5f6368',
          '140': '#1c1c1e'
        }
      }
    }
  }
}
// Documentation: primary blue neutrals redesigned to more neutral grays.
// Chroma reduced to ~2% vs default 10%.
// Reason: financial brand identity requires visual sobriety.

Checkpoint​

By the end of this tutorial you should know:

  • At which points the engine accepts overrides (grayscale, neutrals)
  • The Study → Test → Document cycle before any override
  • Why never to edit data/semantic/ manually
  • Why not to override txtOn directly — use txtOnStrategy instead
  • Distinguish a legitimate override from an unnecessary one and a problematic one

Next step​

You have completed N2. You understand how the system was built and can govern it responsibly.

If you want to go deeper on configuring a complete theme from scratch, continue with N2-04 · Anatomy of a theme.

If you want to advance to technical construction in code, start N3 with N3-01 · The token contract.

References​