Tags

Tags are visual indicators used to highlight notable attributes of items and draw viewer attention to important characteristics. They provide quick, scannable context without overwhelming the interface.

Design

When to Use Tags

Use tags to:

• Highlight newly added or updated items
• Display important item attributes (status, priority, category)
• Provide quick visual context in lists and data displays
• Draw attention to notable characteristics

Variants

Categorical Tags

Use tags to display status, priority, or category information: - Status indicators (Active, Pending, Complete) - Priority levels (High, Medium, Low) - Category labels (Department, Type, Region)

Numerical Tags

Use tags to display counts, quantities, or numerical information:

• Unread message counts (3, 12, 99+)
• Task counts (5 tasks, 2 pending)
• Item quantities (15 items, 3 new)

Color

Use colors strategically to convey meaning and maintain consistency:

Tag colors should always use a [color name] 4 for the background and the corresponding [color name] 1 for the text. For example, a green tag would use Green 4 for the background and Green 1 for the text.

Usage Guidelines

Text Content

• Keep text concise - prefer one or two-word keywords
• Avoid phrases or full sentences
• Use consistent capitalization (all-caps recommended)
• Choose descriptive, meaningful labels

Visual Consistency

• Use different colors when displaying multiple tags together to improve scannability
• Maintain the same color for identical values across your application (e.g., all "High" priority tags should use the same color)
• Keep consistent sizing within the same interface
• Ensure sufficient contrast for accessibility

Accessibility

• Tags must have sufficient color contrast (4.5:1 ratio minimum)
• Use accessibilityText parameter when tag meaning isn't clear from visual context
• Don't rely solely on color to convey information

Development

Basic Tag Implementation

a!tagField(
  labelPosition: "COLLAPSED",
  tags: {
    a!tagItem(
      text: "NEW",
      backgroundColor: "ACCENT"
    )
  }
)

Multiple Tags with Different Colors

a!tagField(
  labelPosition: "COLLAPSED",
  tags: {
    a!tagItem(
      text: "URGENT",
      backgroundColor: "NEGATIVE"
    ),
    a!tagItem(
      text: "CUSTOMER FACING",
      backgroundColor: "ACCENT"
    ),
    a!tagItem(
      text: "IN PROGRESS",
      backgroundColor: "SECONDARY"
    )
  },
  size: "STANDARD"
)

Tags with Custom Styling

a!tagField(
  labelPosition: "COLLAPSED",
  tags: {
    a!tagItem(
      text: "HIGH PRIORITY",
      backgroundColor: "NEGATIVE",
      textColor: "STANDARD"
    ),
    a!tagItem(
      text: "REVIEWED",
      backgroundColor: "POSITIVE",
      textColor: "STANDARD"
    )
  },
  align: "START",
  size: "SMALL"
)

Tags in Data Display Context

a!localVariables(
  local!items: {
    {id: 1, name: "Project Alpha", status: "Active", priority: "High"},
    {id: 2, name: "Project Beta", status: "Pending", priority: "Medium"},
    {id: 3, name: "Project Gamma", status: "Complete", priority: "Low"}
  },
  a!gridField(
    label: "Project Status",
    data: local!items,
    columns: {
      a!gridColumn(
        label: "Project Name",
        value: fv!row.name
      ),
      a!gridColumn(
        label: "Status",
        value: a!tagField(
          labelPosition: "COLLAPSED",
          tags: {
            a!tagItem(
              text: fv!row.status,
              backgroundColor: if(
                fv!row.status = "Active",
                "POSITIVE",
                if(
                  fv!row.status = "Pending",
                  "SECONDARY",
                  "ACCENT"
                )
              )
            )
          }
        )
      ),
      a!gridColumn(
        label: "Priority",
        value: a!tagField(
          labelPosition: "COLLAPSED",
          tags: {
            a!tagItem(
              text: fv!row.priority,
              backgroundColor: if(
                fv!row.priority = "High",
                "NEGATIVE",
                if(
                  fv!row.priority = "Medium",
                  "ACCENT",
                  "SECONDARY"
                )
              )
            )
          }
        )
      )
    }
  )
)

Tag Item Properties

• text: Display text for the tag
• backgroundColor: Color scheme. Accepts semantic names (ACCENT, POSITIVE, NEGATIVE, SECONDARY) or specific palette colors (e.g., Green 4, Orange 4, Red 4).
• textColor: Color scheme. Use the corresponding [color name] 1 for the text color. For example, if backgroundColor is Green 4, textColor should be Green 1. Use the STANDARD value if you've chosen a semantic color for the background to maintain proper text contrast.
• link: Optional link for interactive tags