Skip to main content

FUI2015: CSS variable is not in the contract vocabulary

moderate

A CSS variable reference is shaped like your design tokens but is absent from the approved vocabulary.

Details

diagnostic
{
  "code": "FUI2015",
  "ruleId": "tokens/css-vars-must-be-defined",
  "category": "Tokens",
  "defaultSeverity": "moderate",
  "lifecycle": "experimental",
  "fixAvailable": false,
  "evidenceRequired": true
}

Guidance

## What it means

Fragments found a primary `var(--token)` reference that belongs to your contract's token family but is not defined by its declared token sources. The finding names the unknown variable, property, and source location.

## Why it matters

An unknown variable can silently fall back, inherit, or render differently between applications. It also gives people and agents a token name that the design-system owner cannot version or govern.

## Before

This component references an invented contract token:

```scss .cardTitle { color: var(--fui-color-card-title); } ```

## Repair

List the approved vocabulary with `npx @usefragments/cli tokens list`, then replace the reference with the existing token that has the intended role:

```scss .cardTitle { color: var(--fui-text-primary); } ```

If the role is genuinely new, add it to a declared token source and have the design-system owner approve the resulting contract revision before using it. Do not define the variable inside a random component file merely to silence the finding.

## Intentional exception

Use a narrow, expiring exception only for a compatibility boundary whose token cannot yet be moved into the contract:

```scss // @fragments-expect-error FUI2015 reason="embedded SDK token tracked in DS-728" expires="2026-12-31" .embeddedWidget { color: var(--fui-color-sdk-foreground); } ```

Do not suppress an entire token directory or regenerate a baseline. Review the exception with `npx @usefragments/cli check --list-suppressions`.

## Verify the change

Run `npx @usefragments/cli check --changed --format agent` and confirm FUI2015 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.