DTCG border tokens: author, transform, and verify composite borders

First, name the report target that the fixture is meant to follow. The examples below target the published DTCG 2025.10 format indicated by the captured DTCG glossary. The glossary deliberately provides high-level terminology instead of the complete technical contract, so a production workflow should retain the exact report or schema URI with the source file and recheck it when the report changes.

The version pin matters because a familiar-looking JSON object may be accepted for several different reasons. It might conform to a published format, match a tool's import convention, or simply parse as JSON. Those claims aren't equivalent. A successful design-tool preview has the same limit: it demonstrates behavior in that tool under the tested conditions, not portable support everywhere else.

The portable border concept coordinates three named values: color, width, and style. Border radius is a separate decision. It changes geometry rather than the stroke itself, and the Tokens Studio documentation also treats it separately. Don't add side selection, detailed dash patterns, CSS logical properties, or browser-specific serialization to the composite unless the pinned contract and chosen tool explicitly support them.

That boundary keeps a DTCG border from becoming a bag for every CSS property containing the word border. The source records a design decision. A later mapping decides whether it becomes three CSS longhands, a shorthand, native-platform fields, or another target representation.

The fixture below defines typed primitive inputs and one semantic composite. Its color, width, and stroke style remain reusable, while the semantic token states that they form the standard boundary treatment. Descriptions capture intent. They help reviewers tell an intentional contract from a convenient grouping.

{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "color": {
    "border": {
      "neutral": {
        "$type": "color",
        "$description": "Neutral boundary color for standard controls and panels.",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.45, 0.47, 0.50],
          "alpha": 1,
          "hex": "#737880"
        }
      }
    }
  },
  "dimension": {
    "border": {
      "thin": {
        "$type": "dimension",
        "$description": "Standard single-pixel border at the target CSS scale.",
        "$value": { "value": 1, "unit": "px" }
      }
    }
  },
  "stroke": {
    "solid": {
      "$type": "strokeStyle",
      "$description": "Continuous stroke for standard interface boundaries.",
      "$value": "solid"
    }
  },
  "border": {
    "control": {
      "default": {
        "$type": "border",
        "$description": "Default boundary shared by standard interactive controls.",
        "$value": {
          "color": "{color.border.neutral}",
          "width": "{dimension.border.thin}",
          "style": "{stroke.solid}"
        }
      }
    }
  }
}

The references are part of the authored source too. Their presence doesn't prove that a resolver found compatible targets. Keep the authored object separate from the resolved expectation so a missing target, cycle, or incompatible type can't disappear inside generated output.

{
  "tokenPath": "border.control.default",
  "resolvedExpectation": {
    "color": {
      "colorSpace": "srgb",
      "components": [0.45, 0.47, 0.50],
      "alpha": 1,
      "hex": "#737880"
    },
    "width": { "value": 1, "unit": "px" },
    "style": "solid"
  },
  "resolutionStatus": "unobserved"
}

A composite fits when the three properties form one stable decision. It isn't automatically the best representation for every border. Ask what should happen when one property changes, who owns that change, and which consumers it may reach.

These choices can work together. The example uses separate primitive properties inside a semantic composite. A component can consume that shared composite until evidence shows that it needs independent change authority. If only a data table divider must become thinner while inputs, cards, and menus stay unchanged, that supports a table-owned decision or documented exception. It isn't a reason to weaken every shared border.

Modes and states also shape the boundary. Light and dark modes may resolve the same semantic border name to different colors while preserving its width and style. A focus or error state may need a separate semantic border because its meaning differs, even when the current values match. Name the intent first. Don't infer shared ownership from identical values.

A transformation contract records what you intend a named tool to do. Include the tool and exact version, configuration identity, source identity or hash, target platform, naming rule, output path, and expected properties. Until the command has run and you've captured the artifact, the result remains an expectation.

{
  "translationContract": {
    "tool": "UNRESOLVED",
    "version": "UNRESOLVED",
    "configuration": "UNRESOLVED",
    "inputFile": "tokens/border.tokens.json",
    "inputHash": "UNRESOLVED",
    "target": "css-custom-properties",
    "expectedSymbols": [
      "--border-control-default-color",
      "--border-control-default-width",
      "--border-control-default-style"
    ],
    "outputFile": "UNRESOLVED"
  },
  "artifactObservation": "UNRESOLVED"
}

For a CSS target, a project might choose to emit longhands. They make each resolved property inspectable and avoid depending on a tool's shorthand ordering. That's a project choice, not a DTCG requirement.

:root {
  --border-control-default-color: #737880;
  --border-control-default-width: 1px;
  --border-control-default-style: solid;
}

.control {
  border-color: var(--border-control-default-color);
  border-width: var(--border-control-default-width);
  border-style: var(--border-control-default-style);
}

Pick a consumer that matters, such as the default text input in the account form. Don't verify an anonymous swatch or isolated rectangle and assume the application is covered. A named consumer exposes selector scope, cascade, state handling, and local overrides.

1. 1

   Capture the emitted artifact

   Record the generated file identity, build or package version, and exact declarations for the border token. Compare them with the expected symbols and values.

2. 2

   Confirm the consumer mapping

   Identify the selector, utility, component prop, or platform mapping that connects the emitted artifact to the named component. A correct artifact can still remain unused.

3. 3

   Inspect computed values

   Record the target element's computed border color, width, and style. Check whether shorthands, higher-specificity selectors, inline styles, or component variants replace them.

4. 4

   Exercise required modes and states

   Repeat the observation in every in-scope mode and state, including default, hover, focus, disabled, and error where supported. Mark unsupported or out-of-scope cases explicitly.

5. 5

   Check protected surfaces

   Change the source border in a controlled branch or fixture. Confirm that intended consumers change while named protected surfaces remain stable.

6. 6

   Record exceptions and disposition

   Attach every accepted local override to a scope, reason, owner, and review condition. Choose accept, revise, or block from the recorded evidence.

An intentionally obvious controlled change works well, such as changing the test width from 1px to 3px in a non-release fixture. If the input changes but an unrelated card doesn't, the mapping may have the intended reach. Restore the approved value after the trace. The goal is to expose the dependency path, not approve the temporary design.

Keep this record with the test evidence or release decision. Unresolved fields stay visible because an honest blank is more useful than a plausible claim nobody checked.

{
  "source": {
    "file": "tokens/border.tokens.json",
    "hash": "UNRESOLVED",
    "contractTarget": "DTCG 2025.10",
    "tokenPath": "border.control.default",
    "references": {
      "color": "color.border.neutral",
      "width": "dimension.border.thin",
      "style": "stroke.solid"
    },
    "resolvedExpectation": {
      "colorHex": "#737880",
      "width": "1px",
      "style": "solid"
    }
  },
  "translation": {
    "tool": "UNRESOLVED",
    "version": "UNRESOLVED",
    "configuration": "UNRESOLVED",
    "target": "css-custom-properties",
    "artifactPath": "UNRESOLVED",
    "artifactHash": "UNRESOLVED",
    "observedSymbols": "UNRESOLVED",
    "observedValues": "UNRESOLVED"
  },
  "consumer": {
    "name": "Account form text input",
    "buildIdentity": "UNRESOLVED",
    "selectorOrMapping": "UNRESOLVED",
    "modes": ["light", "dark"],
    "states": ["default", "hover", "focus", "disabled", "error"],
    "expectedComputedValues": {
      "borderColor": "#737880",
      "borderWidth": "1px",
      "borderStyle": "solid"
    },
    "observedComputedValues": "UNRESOLVED"
  },
  "protectedSurfaces": [
    "Data table row dividers",
    "Decorative separators"
  ],
  "exceptions": [],
  "correctionOwner": "UNRESOLVED",
  "disposition": "block",
  "reason": "Artifact and runtime observations have not been captured."
}

Choose accept only when the in-scope source, resolution, artifact, mapping, and consumer observations agree and any exceptions are approved. Choose revise when the intended decision is sound but a correctable mapping, configuration, or local override is wrong. Choose block when required evidence is absent, references don't resolve, the wrong consumers change, or a protected surface is affected.

The order matters. If the computed border is wrong, first confirm that the application loaded the reviewed artifact. If it did, inspect the selector and cascade. Don't edit the primitive source before locating the break: that can change every correct consumer while leaving the faulty override untouched.

Identity Forge supplies implementation-ready design kits and DTCG token exports. The frozen product evidence doesn't establish that a current Identity Forge kit exports a DTCG border composite, so the fixture in this guide is illustrative and must not be attributed to the product.

Even when an Identity Forge export is the upstream source, the consuming project still owns translation configuration, naming, application mapping, rendered verification, exceptions, and release approval. A source artifact can make the decision portable. It can't observe your build, cascade, component variants, or production surface for you.

• DTCG Glossary: Defines aliases, composite design tokens, design tools, and translation tools at a high level, and identifies a border composite as color, width, and style.
• Border - Composite - Tokens Studio for Figma: Documents Tokens Studio border authoring and Figma application behavior, including border properties supplied directly or through references and border radius as a separate concern.
• DTCG Tokens - Terrazzo: Shows DTCG tokens as nested JSON data and places code generation within a translation tool's implementation context.
• tokens.json Manifest - Cobalt: Documents an implementation-specific DTCG-compatible manifest, supported token types, and tool extensions, illustrating why tool support must be recorded separately from the portable contract.
• Design tokens with confidence: Describes the core border composite value as color, width, and style in a DTCG-oriented overview.
• The developer's guide to design tokens and CSS variables: Distinguishes platform-neutral design-token data from CSS custom properties used as a browser implementation layer.
• Component tokens vs semantic tokens: when to add a component layer: Provides an existing decision framework based on change scope, named consumers, modes, states, protected surfaces, and ownership.
• Identity Forge: Documents Identity Forge design kits and their implementation artifacts, including token exports, while not establishing that a current kit exports a border composite.