token.json

{
  "token": {
    "kind": "token",
    "identifier": "color-text-primary",
    "metadata": [
      {
        "kind": "description",
        "value": "The default color for body text, headings, and labels. Provides the highest-contrast text color for standard reading content on default background surfaces."
      },
      {
        "kind": "status",
        "status": "stable",
        "platformStatus": {
          "css": {
            "status": "stable",
            "since": "2.0.0"
          },
          "ios": {
            "status": "stable",
            "since": "2.1.0"
          },
          "android": {
            "status": "stable",
            "since": "2.2.0"
          },
          "figma": {
            "status": "stable",
            "since": "2.0.0"
          }
        }
      },
      {
        "kind": "since",
        "value": "2.0.0"
      },
      {
        "kind": "tags",
        "items": [
          "color",
          "text",
          "body"
        ]
      },
      {
        "kind": "category",
        "value": "semantic"
      },
      {
        "kind": "aliases",
        "items": [
          "color.text.default",
          "color.text.body"
        ]
      },
      {
        "kind": "summary",
        "value": "Default body text color for light and dark surfaces."
      },
      {
        "kind": "links",
        "items": [
          {
            "kind": "source",
            "url": "https://code.acme.com/design-system/src/tokens/color/text.tokens.json",
            "label": "Token source file"
          },
          {
            "kind": "documentation",
            "url": "https://design.acme.com/tokens/color-text-primary",
            "label": "Token documentation"
          },
          {
            "kind": "related",
            "url": "https://design.acme.com/tokens/color-text-secondary",
            "label": "color-text-secondary"
          },
          {
            "kind": "related",
            "url": "https://design.acme.com/tokens/color-text-tertiary",
            "label": "color-text-tertiary"
          }
        ]
      }
    ],
    "tokenType": "color",
    "source": {
      "file": "tokens/color.tokens.json",
      "path": "color.text.primary"
    },
    "documentBlocks": [
      {
        "kind": "purpose",
        "useCases": [
          {
            "description": "When applying color to body text, headings, and form labels on default background surfaces.",
            "kind": "positive"
          },
          {
            "description": "When building components that display primary reading content that must adapt across color modes.",
            "kind": "positive"
          },
          {
            "description": "When placing text on dark or colored background surfaces.",
            "kind": "negative",
            "alternative": {
              "identifier": "color-text-inverse",
              "rationale": "This token is optimized for contrast against light backgrounds. Using it on dark or saturated surfaces will fail contrast requirements."
            }
          },
          {
            "description": "When the text is inside a component that supplies its own scoped color tokens (e.g., text on a filled button).",
            "kind": "negative",
            "alternative": {
              "identifier": "color-text-on-action",
              "rationale": "Component-scoped tokens account for the specific background they sit on. Applying a general text token to a scoped context risks contrast failures."
            }
          }
        ],
        "agents": {
          "intent": "Clarify when to use the color-text-primary token versus other text color tokens.",
          "disambiguation": [
            {
              "entity": "color-text-secondary",
              "distinction": "Use color-text-primary for body text and headings; use color-text-secondary for supplementary or de-emphasized text."
            },
            {
              "entity": "color-text-on-action",
              "distinction": "Use color-text-primary on standard surfaces; use color-text-on-action on filled interactive elements like buttons."
            }
          ],
          "keywords": [
            "when to use",
            "text color",
            "primary",
            "body text"
          ]
        }
      },
      {
        "kind": "guideline",
        "items": [
          {
            "guidance": "Use for all body text, headings, and form labels on default background surfaces.",
            "rationale": "A single primary text color ensures visual consistency and meets WCAG 2.1 AA contrast requirements against the system's default background.",
            "kind": "encouraged",
            "category": "visual-design"
          },
          {
            "guidance": "Do not override this token's value at the component level. Use color-text-secondary or color-text-tertiary for reduced emphasis.",
            "rationale": "Overriding the primary text color creates inconsistency. The system provides lower-emphasis text tokens for visual hierarchy.",
            "kind": "prohibited",
            "category": "visual-design"
          },
          {
            "guidance": "This color meets a 15.3:1 contrast ratio against color-background-default in light mode.",
            "rationale": "Exceeds WCAG 2.1 AAA requirements (7:1 for normal text), ensuring readability for users with low vision.",
            "kind": "informational",
            "category": "accessibility",
            "criteria": [
              {
                "url": "https://www.w3.org/TR/WCAG22/#contrast-minimum",
                "kind": "reference"
              },
              {
                "url": "https://www.w3.org/TR/WCAG22/#contrast-enhanced",
                "kind": "reference"
              }
            ]
          }
        ],
        "agents": {
          "intent": "Enforce correct usage rules for the color-text-primary token.",
          "constraints": [
            {
              "rule": "Do not use color-text-primary on colored or image backgrounds without verifying contrast.",
              "level": "must-not"
            },
            {
              "rule": "Always pair with a background token from the same surface family.",
              "level": "should"
            }
          ],
          "keywords": [
            "rules",
            "contrast",
            "pairing",
            "surface"
          ]
        }
      },
      {
        "kind": "accessibility",
        "wcagLevel": "AAA",
        "colorContrast": [
          {
            "foreground": "color-text-primary",
            "background": "color-background-default",
            "contrastRatio": 15.3,
            "level": "AAA",
            "context": "Primary text on default background in light mode."
          },
          {
            "foreground": "color-text-primary",
            "background": "color-background-subtle",
            "contrastRatio": 13.8,
            "level": "AAA",
            "context": "Primary text on subtle background (card surface) in light mode."
          }
        ],
        "agents": {
          "intent": "Provide contrast ratios and WCAG compliance data for the color-text-primary token.",
          "keywords": [
            "WCAG",
            "contrast",
            "AA",
            "AAA",
            "accessibility",
            "ratio"
          ]
        }
      }
    ],
    "agents": {
      "intent": "Apply the primary text color for body content, headings, and labels on default background surfaces.",
      "constraints": [
        {
          "rule": "Do not use on dark or colored background surfaces.",
          "level": "must-not"
        },
        {
          "rule": "Do not override this token value at the component level.",
          "level": "must-not"
        }
      ],
      "disambiguation": [
        {
          "entity": "color-text-secondary",
          "distinction": "Use primary for default reading content; use secondary for supporting or reduced-emphasis text."
        },
        {
          "entity": "color-text-on-action",
          "distinction": "Use primary on default surfaces; use on-action inside filled interactive components."
        }
      ],
      "keywords": [
        "color",
        "text",
        "primary",
        "body",
        "heading",
        "label",
        "foreground"
      ]
    }
  }
}