Skip to main content

FUI2017: Local token differs from its declared upstream source

moderate

A local token differs from the single declared upstream token it is meant to follow.

Details

diagnostic
{
  "code": "FUI2017",
  "ruleId": "tokens/upstream-drift",
  "category": "Tokens",
  "defaultSeverity": "moderate",
  "lifecycle": "experimental",
  "fixAvailable": false,
  "evidenceRequired": true
}

Guidance

## What it means

Fragments compared an authored local token with its same-name upstream token or explicit `tokens.aliases` target and found different normalized values. The evidence names both authorities, their values, and their source locations.

## Why it matters

Consumers can believe they use the shared token while rendering a different value locally. Automated replacement is unsafe because it could recommend the drifting local value and spread the mismatch.

## Before

The local value differs from the declared upstream `--brand` value:

```css :root { --brand: #111111; } ```

## Repair

Confirm the upstream manifest pin and intended authority, then update the local definition to the exact upstream value:

```css :root { --brand: #222222; } ```

If the local token intentionally represents a different role, give it a distinct semantic name and update the explicit `tokens.aliases` mapping with design-system-owner approval. Do not change the upstream pin or remove an alias simply to make the warning disappear.

## Intentional exception

When a time-bounded migration requires the mismatch, attach the exception to the local definition and name its owner and expiry:

```css // @fragments-expect-error FUI2017 reason="brand rollout tracked in DS-744" expires="2026-12-31" :root { --brand: #111111; } ```

Do not baseline the mismatch. Review it with `npx @usefragments/cli check --list-suppressions` and ensure `npx @usefragments/cli check --check-expired` remains green.

## Verify the change

Run `npx @usefragments/cli check --changed --format agent` and confirm FUI2017 is absent or the specific reviewed exception is listed. Then run `npx @usefragments/cli check --changed --ci`.

Intentional exception? Use a narrow, reasoned directive from the in-source exception reference.

Next steps

  • RulesThe rules that emit FUI codes.
  • ExceptionsIn-source allows and Cloud exceptions.