Contract | Fragments

FCID

node node_modules/@usefragments/cli/dist/loop.js card | sed -n 2p   # FCID: `…`

The FCID appears on the card, in every receipt, and on the Contract page in Fragments Cloud. Change the manifest, get a new FCID, and pin it again before a pull request can pass. A head evaluated against a different FCID than the pin is indeterminate.

Shape of the file: fragments.manifest.json.

Rules the pin arms

Each rule emits a versioned FUI code. Explain pages live at /errors.

Components

Components rules
Rule	FUI code	Tier	Title
`components/unknown-prop`	`FUI6005`	Opt-in	Component prop is unknown
`components/forbidden-prop-value`	`FUI6004`	Opt-in	Prop value is forbidden
`components/preferred-component`	`FUI1002`	Opt-in	Preferred component should be used
`components/prefer-library`	`FUI1004`	Contract	Library component should be preferred
`components/shadow-component`	`FUI1007`	Contract	Component shadows a canonical primitive

Props

Props rules
Rule	FUI code	Tier	Title
`props/invalid-value`	`FUI6002`	Opt-in	Prop value is invalid

Imports

Imports rules
Rule	FUI code	Tier	Title
`imports/preferred-path`	`FUI1003`	Opt-in	Import should use the preferred path

Styles

Styles rules
Rule	FUI code	Tier	Title
`styles/no-raw-color`	`FUI2005`	Opt-in	Raw color should use a token
`styles/no-raw-dimensions`	`FUI2004`	Opt-in	Raw dimension should use a token
`styles/no-raw-spacing`	`FUI2006`	Opt-in	Raw spacing should use the scale
`styles/no-raw-typography`	`FUI2016`	Opt-in	Raw typography should use a token

Tailwind

Tailwind rules
Rule	FUI code	Tier	Title
`tailwind/arbitrary-color`	`FUI2007`	Opt-in	Tailwind arbitrary color should use a token
`tailwind/arbitrary-spacing`	`FUI2008`	Opt-in	Tailwind arbitrary spacing should use the scale
`tailwind/forbidden-palette`	`FUI2009`	Opt-in	Tailwind palette is forbidden
`tailwind/off-scale-spacing-token`	`FUI2011`	Opt-in	Tailwind spacing token is off scale
`tailwind/raw-color-via-token`	`FUI2010`	Opt-in	Tailwind color should use a resolved token
`tailwind/unknown-class`	`FUI2012`	Opt-in	Tailwind class is unknown

Tokens

Tokens rules
Rule	FUI code	Tier	Title
`tokens/require-dual-fallback`	`FUI2003`	Opt-in	Token fallback is required
`tokens/css-vars-must-be-defined`	`FUI2015`	Contract	CSS variable is not in the contract vocabulary
`tokens/upstream-drift`	`FUI2017`	Contract	Local token differs from its declared upstream source

Theme

Theme rules
Rule	FUI code	Tier	Title
`theme/no-theme-coupled-literal`	`FUI2014`	Opt-in	Theme-coupled literal should use a semantic token

Accessibility

Accessibility rules
Rule	FUI code	Tier	Title
`a11y/required-accessible-name`	`FUI3001`	Opt-in	Accessible name is required
`a11y/standard`	`FUI3002`	Opt-in	Accessibility standard failed

Composition

Composition rules
Rule	FUI code	Tier	Title
`composition/cardinality`	`FUI5003`	Opt-in	Too many of a component in one region
`composition/co-occurrence`	`FUI5004`	Opt-in	Required companion component is missing from the region

Config schema

Optional fragments.config.ts scopes token sources, topology, and rule records. The manifest is still the contract the loop and the gate evaluate.

Governance policy

Governance policy configuration fields
Field	Type	Required	Description
`govern.agent`	`object`	No	Agent repair-order guidance consumed when presenting deterministic fixes.
`govern.agents`	`Record<string, object>`	No	Agent-id keyed rule overrides for supported agent-specific governance policies.
`govern.audit`	`object`	No	Reserved audit compatibility object; undeclared child keys are reported as inert.
`govern.canonicalBridges`	`object[]`	No	Confirmed mappings from an underlying library export to the approved local wrapper. The wrapper's implementationFiles scope permits its direct underlying import.
`govern.canonicalSources`	`object[]`	No	Canonical component authorities: npm packages, repository directories, or registry receipts whose included exports arm canonical-component rules.
`govern.ci`	`object`	No	Governance CI rendering options. Under `--ci`, `failOnWarnings` defaults to `true` when absent; set it to `false` to keep warning findings reported but advisory. `failOnInert` is opt-in and makes inert-config diagnostics (FUI9004-FUI9008) fail the verdict; `--allow-inert` bypasses the inert gates. `failOnAdoptionRegression` is opt-in and makes `check --ci` compare the current component-identity adoption percentage with the committed `.fragments/adoption-baseline.json` floor.
`govern.components`	`Record<string, object>`	No	Component-keyed governance records for canonical component metadata and prop policy.
`govern.extends`	`string[]`	No	Shared governance config modules to extend before applying this file's declarations.
`govern.jsx`	`object[]`	No	Legacy typed JSX-policy records, normalized into the active rule policy.
`govern.overrides`	`object[]`	No	Ordered component-policy overrides selected by component identity fields.
`govern.presets`	`string[]`	No	Versioned governance presets to resolve before applying local rule overrides.
`govern.rules`	`Record<string, unknown>`	No	Rule-id keyed enablement and severity overrides. Only fields consumed by the named rule are valid; unsupported fields are reported as inert config.
`govern.runners`	`Record<string, object>`	No	Reserved runner compatibility map; undeclared child keys are reported as inert.
`govern.scales`	`Record<string, object>`	No	Named numeric scales. Spacing rules bind through style.rawSpacing.mustMatchScale; the built-in spacing policy references `space`.
`govern.severity`	`"error" \| "warn" \| "info"`	No	Default severity for governance rules that do not declare their own severity.
`govern.styles`	`object[]`	No	Legacy typed style-policy records, normalized into the active rule policy.
`govern.tailwind`	`object`	No	Tailwind palette allow/deny policy used by Tailwind governance rules.

Token sources

Token sources configuration fields
Field	Type	Required	Description
`tokens.aliases`	`Record<string, string>`	No	Explicit local-name -> upstream-name mappings for cross-authority drift checks.
`tokens.enabled`	`boolean`	No	Enable token comparison in style diffs (default: true)
`tokens.exclude`	`string[]`	No	Glob patterns to exclude
`tokens.format`	`"auto" \| "css" \| "scss" \| "dtcg" \| "tailwind"`	No	Token source format detection. "auto" infers supported formats from the file extension, including statically analyzable TypeScript/JavaScript modules.
`tokens.include`	`string[]`	No	Glob patterns for files to scan for tokens e.g., ["src/styles/theme.scss", "src/styles/variables.css"]
`tokens.namespace`	`string`	No	Vendor namespace for Fragments extensions in DTCG files (default: 'com.usefragments')
`tokens.packages`	`string[]`	No	npm package names whose shipped `fragments.json` token vocabulary seeds the known-token set (e.g. `["@usefragments/ui"]`). DECLARED-manifest ingest — the parser reads each package's published `fragments.json` and merges its token names into the vocabulary `tokens/css-vars-must-be-defined` consumes, so a consumer using those `--fui-*` vars is not flagged as drift. Never globs node_modules SCSS — only the declared manifest is trusted, keeping the no-inference mandate intact.
`tokens.sources`	`object[]`	No	Repo-root-relative token source files/globs for monorepos and Cloud setup. Set each source to format "auto" for TypeScript or JavaScript token modules.
`tokens.themeSelectors`	`Record<string, string>`	No	Map CSS selectors to theme names
`tokens.upstream`	`object[]`	No	Deterministic pins for upstream token manifests; local scans never fetch them.

Local identity decisions

Local identity decisions configuration fields
Field	Type	Required	Description
`identity.decisions`	`object[]`	No	Authored sanctions, rejections, and dismissals keyed by portable component identity.

Token modules

Point tokens.sources at a TypeScript or JavaScript module when tokens are not in CSS.

import type { FragmentsConfig } from "@usefragments/core";

export default {
  tokens: {
    sources: [{ path: "src/theme/tokens.ts", format: "auto" }],
  },
} satisfies FragmentsConfig;

Worked config

import type { FragmentsConfig } from "@usefragments/core";

export default {
  "app": {
    "path": ".",
    "include": [
      "src/**/*.{ts,tsx,css,scss}"
    ]
  },
  "components": [
    "src/components/**/*.tsx"
  ],
  "tokens": {
    "sources": [
      {
        "path": "src/theme.ts",
        "format": "auto"
      }
    ],
    "packages": [
      "@acme/design-tokens"
    ],
    "aliases": {
      "colors.brand": "--acme-color-brand"
    }
  },
  "govern": {
    "canonicalBridges": [
      {
        "underlying": {
          "packageName": "@mui/material",
          "exportName": "Button"
        },
        "local": {
          "componentKey": "src/components/Button#Button",
          "moduleSpecifier": "@/components/Button",
          "exportName": "Button",
          "implementationFiles": [
            "src/components/Button/Button.tsx"
          ]
        },
        "decision": {
          "state": "confirmed",
          "source": "authored"
        }
      }
    ],
    "styles": [
      {
        "kind": "style.rawColors.forbid",
        "except": [
          "transparent"
        ],
        "prefer": "token",
        "severity": "warn",
        "exclude": [
          {
            "glob": "src/legacy/vendor/**",
            "reason": "vendor drop, tracked in DS-611"
          }
        ]
      }
    ],
    "rules": {
      "styles/no-raw-color": {
        "enabled": true,
        "severity": "warn"
      }
    }
  }
} satisfies FragmentsConfig;

Next steps

ConnectPin this FCID on a binding.Verdicts and receiptsWhat evaluate() returns for an exact head.FUI codesExplain pages for every finding.