Atlassian

The genuine design.md file published by Atlassian.
Visit website Last updated 07/22/2026
Colors
Typography
Spacing
#0: 0rem
#025: 0.125rem
#050: 0.25rem
#075: 0.375rem
#100: 0.5rem
Rounded
#xsmall: 0.125rem
#small: 0.25rem
#medium: 0.375rem
DESIGN.md
---
version: alpha
revision: 0.0.7
theme: light
name: Atlassian
colors:
  'text': '#292A2E'
  'text-accent-lime': '#4C6B1F'
  'text-accent-lime-bolder': '#37471F'
  'text-accent-red': '#AE2E24'
  'text-accent-red-bolder': '#5D1F1A'
  'text-accent-orange': '#9E4C00'
  'text-accent-orange-bolder': '#693200'
  'text-accent-yellow': '#7F5F01'
  'text-accent-yellow-bolder': '#533F04'
  'text-accent-green': '#216E4E'
  'text-accent-green-bolder': '#164B35'
  'text-accent-teal': '#206A83'
  'text-accent-teal-bolder': '#164555'
  'text-accent-blue': '#1558BC'
  'text-accent-blue-bolder': '#123263'
  'text-accent-purple': '#803FA5'
  'text-accent-purple-bolder': '#48245D'
  'text-accent-magenta': '#943D73'
  'text-accent-magenta-bolder': '#50253F'
  'text-accent-gray': '#505258'
  'text-accent-gray-bolder': '#1E1F21'
  'text-code-accent-1': '#943D73'
  'text-code-accent-2': '#1558BC'
  'text-code-comments': '#505258'
  'text-code-default': '#505258'
  'text-code-functions': '#216E4E'
  'text-code-gutter': '#6B6E76'
  'text-code-keywords': '#AE2E24'
  'text-code-numbers': '#7F5F01'
  'text-code-operators': '#292A2E'
  'text-code-strings': '#4C6B1F'
  'text-code-tags': '#9E4C00'
  'text-disabled': '#080F214A'
  'text-inverse': '#FFFFFF'
  'text-selected': '#1868DB'
  'text-brand': '#1868DB'
  'text-danger': '#AE2E24'
  'text-danger-bolder': '#5D1F1A'
  'text-warning': '#9E4C00'
  'text-warning-inverse': '#292A2E'
  'text-warning-bolder': '#693200'
  'text-success': '#4C6B1F'
  'text-success-bolder': '#37471F'
  'text-discovery': '#803FA5'
  'text-discovery-bolder': '#48245D'
  'text-information': '#1558BC'
  'text-information-bolder': '#123263'
  'text-subtlest': '#6B6E76'
  'text-subtle': '#505258'
  'link': '#1868DB'
  'link-pressed': '#1558BC'
  'link-visited': '#803FA5'
  'link-visited-pressed': '#48245D'
  'icon': '#292A2E'
  'icon-accent-lime': '#6A9A23'
  'icon-accent-red': '#C9372C'
  'icon-accent-orange': '#E06C00'
  'icon-accent-yellow': '#B38600'
  'icon-accent-green': '#22A06B'
  'icon-accent-teal': '#2898BD'
  'icon-accent-blue': '#357DE8'
  'icon-accent-purple': '#AF59E1'
  'icon-accent-magenta': '#CD519D'
  'icon-accent-gray': '#7D818A'
  'icon-disabled': '#080F214A'
  'icon-inverse': '#FFFFFF'
  'icon-selected': '#1868DB'
  'icon-brand': '#1868DB'
  'icon-danger': '#C9372C'
  'icon-warning': '#E06C00'
  'icon-warning-inverse': '#292A2E'
  'icon-success': '#6A9A23'
  'icon-discovery': '#AF59E1'
  'icon-information': '#357DE8'
  'icon-subtlest': '#6B6E76'
  'icon-subtle': '#505258'
  'border': '#0B120E24'
  'border-accent-lime': '#6A9A23'
  'border-accent-lime-subtle': '#B3DF72'
  'border-accent-red': '#E2483D'
  'border-accent-red-subtle': '#FD9891'
  'border-accent-orange': '#E06C00'
  'border-accent-orange-subtle': '#FBC828'
  'border-accent-yellow': '#B38600'
  'border-accent-yellow-subtle': '#EED12B'
  'border-accent-green': '#22A06B'
  'border-accent-green-subtle': '#7EE2B8'
  'border-accent-teal': '#2898BD'
  'border-accent-teal-subtle': '#9DD9EE'
  'border-accent-blue': '#357DE8'
  'border-accent-blue-subtle': '#8FB8F6'
  'border-accent-purple': '#AF59E1'
  'border-accent-purple-subtle': '#D8A0F7'
  'border-accent-magenta': '#CD519D'
  'border-accent-magenta-subtle': '#F797D2'
  'border-accent-gray': '#7D818A'
  'border-accent-gray-subtle': '#B7B9BE'
  'border-code': '#0B120E24'
  'border-disabled': '#0515240F'
  'border-focused': '#4688EC'
  'border-input': '#8C8F97'
  'border-inverse': '#FFFFFF'
  'border-selected': '#1868DB'
  'border-brand': '#1868DB'
  'border-danger': '#E2483D'
  'border-danger-subtle': '#FD9891'
  'border-warning': '#E06C00'
  'border-warning-subtle': '#FBC828'
  'border-success': '#6A9A23'
  'border-success-subtle': '#B3DF72'
  'border-discovery': '#AF59E1'
  'border-discovery-subtle': '#D8A0F7'
  'border-information': '#357DE8'
  'border-information-subtle': '#8FB8F6'
  'border-bold': '#7D818A'
  'background-accent-lime-subtlest': '#EFFFD6'
  'background-accent-lime-subtler': '#D3F1A7'
  'background-accent-lime-subtle': '#94C748'
  'background-accent-lime-bolder': '#5B7F24'
  'background-accent-red-subtlest': '#FFECEB'
  'background-accent-red-subtler': '#FFD5D2'
  'background-accent-red-subtle': '#F87168'
  'background-accent-red-bolder': '#C9372C'
  'background-accent-orange-subtlest': '#FFF5DB'
  'background-accent-orange-subtler': '#FCE4A6'
  'background-accent-orange-subtle': '#FCA700'
  'background-accent-orange-bolder': '#BD5B00'
  'background-accent-yellow-subtlest': '#FEF7C8'
  'background-accent-yellow-subtler': '#F5E989'
  'background-accent-yellow-subtle': '#EED12B'
  'background-accent-yellow-bolder': '#946F00'
  'background-accent-green-subtlest': '#DCFFF1'
  'background-accent-green-subtler': '#BAF3DB'
  'background-accent-green-subtle': '#4BCE97'
  'background-accent-green-bolder': '#1F845A'
  'background-accent-teal-subtlest': '#E7F9FF'
  'background-accent-teal-subtler': '#C6EDFB'
  'background-accent-teal-subtle': '#6CC3E0'
  'background-accent-teal-bolder': '#227D9B'
  'background-accent-blue-subtlest': '#E9F2FE'
  'background-accent-blue-subtler': '#CFE1FD'
  'background-accent-blue-subtle': '#669DF1'
  'background-accent-blue-bolder': '#1868DB'
  'background-accent-purple-subtlest': '#F8EEFE'
  'background-accent-purple-subtler': '#EED7FC'
  'background-accent-purple-subtle': '#C97CF4'
  'background-accent-purple-bolder': '#964AC0'
  'background-accent-magenta-subtlest': '#FFECF8'
  'background-accent-magenta-subtler': '#FDD0EC'
  'background-accent-magenta-subtle': '#E774BB'
  'background-accent-magenta-bolder': '#AE4787'
  'background-accent-gray-subtlest': '#F0F1F2'
  'background-accent-gray-subtler': '#DDDEE1'
  'background-accent-gray-subtle': '#8C8F97'
  'background-accent-gray-bolder': '#6B6E76'
  'background-code-added-highlight': '#DCFFF1'
  'background-code-added-line': '#BAF3DB66'
  'background-code-default': '#FFFFFF'
  'background-code-gutter': '#F0F1F2'
  'background-code-highlight': '#F0F1F2'
  'background-code-removed-highlight': '#FFECEB'
  'background-code-removed-line': '#FFD5D266'
  'background-disabled': '#0515240F'
  'background-input': '#FFFFFF'
  'background-input-hovered': '#F8F8F8'
  'background-input-pressed': '#FFFFFF'
  'background-inverse-subtle': '#00000029'
  'background-inverse-subtle-hovered': '#0000003D'
  'background-inverse-subtle-pressed': '#00000052'
  'background-neutral': '#0515240F'
  'background-neutral-hovered': '#0B120E24'
  'background-neutral-pressed': '#080F214A'
  'background-neutral-subtle': '#00000000'
  'background-neutral-subtle-hovered': '#0515240F'
  'background-neutral-subtle-pressed': '#0B120E24'
  'background-neutral-bold': '#292A2E'
  'background-neutral-bold-hovered': '#3B3D42'
  'background-neutral-bold-pressed': '#505258'
  'background-selected': '#E9F2FE'
  'background-selected-hovered': '#CFE1FD'
  'background-selected-pressed': '#8FB8F6'
  'background-selected-bold': '#1868DB'
  'background-selected-bold-hovered': '#1558BC'
  'background-selected-bold-pressed': '#123263'
  'background-brand-subtlest': '#E9F2FE'
  'background-brand-subtlest-hovered': '#CFE1FD'
  'background-brand-subtlest-pressed': '#ADCBFB'
  'background-brand-bold': '#1868DB'
  'background-brand-bold-hovered': '#1558BC'
  'background-brand-bold-pressed': '#144794'
  'background-brand-boldest': '#1C2B42'
  'background-brand-boldest-hovered': '#123263'
  'background-brand-boldest-pressed': '#144794'
  'background-danger': '#FFECEB'
  'background-danger-hovered': '#FFD5D2'
  'background-danger-pressed': '#FFB8B2'
  'background-danger-subtler': '#FFD5D2'
  'background-danger-subtler-hovered': '#FFB8B2'
  'background-danger-subtler-pressed': '#FD9891'
  'background-danger-subtle': '#FD9891'
  'background-danger-bold': '#C9372C'
  'background-danger-bold-hovered': '#AE2E24'
  'background-danger-bold-pressed': '#872821'
  'background-warning': '#FFF5DB'
  'background-warning-hovered': '#FCE4A6'
  'background-warning-pressed': '#FBD779'
  'background-warning-subtler': '#FCE4A6'
  'background-warning-subtler-hovered': '#FBD779'
  'background-warning-subtler-pressed': '#FBC828'
  'background-warning-subtle': '#FBD779'
  'background-warning-bold': '#FBC828'
  'background-warning-bold-hovered': '#FCA700'
  'background-warning-bold-pressed': '#F68909'
  'background-success': '#EFFFD6'
  'background-success-hovered': '#D3F1A7'
  'background-success-pressed': '#BDE97C'
  'background-success-subtler': '#D3F1A7'
  'background-success-subtler-hovered': '#BDE97C'
  'background-success-subtler-pressed': '#B3DF72'
  'background-success-subtle': '#B3DF72'
  'background-success-bold': '#5B7F24'
  'background-success-bold-hovered': '#4C6B1F'
  'background-success-bold-pressed': '#3F5224'
  'background-discovery': '#F8EEFE'
  'background-discovery-hovered': '#EED7FC'
  'background-discovery-pressed': '#E3BDFA'
  'background-discovery-subtler': '#EED7FC'
  'background-discovery-subtler-hovered': '#E3BDFA'
  'background-discovery-subtler-pressed': '#D8A0F7'
  'background-discovery-subtle': '#D8A0F7'
  'background-discovery-bold': '#964AC0'
  'background-discovery-bold-hovered': '#803FA5'
  'background-discovery-bold-pressed': '#673286'
  'background-information': '#E9F2FE'
  'background-information-hovered': '#CFE1FD'
  'background-information-pressed': '#ADCBFB'
  'background-information-subtler': '#CFE1FD'
  'background-information-subtler-hovered': '#ADCBFB'
  'background-information-subtler-pressed': '#8FB8F6'
  'background-information-subtle': '#8FB8F6'
  'background-information-bold': '#1868DB'
  'background-information-bold-hovered': '#1558BC'
  'background-information-bold-pressed': '#144794'
  'chart-categorical-1': '#357DE8'
  'chart-categorical-2': '#82B536'
  'chart-categorical-3': '#BF63F3'
  'chart-categorical-4': '#F68909'
  'chart-categorical-5': '#1558BC'
  'chart-categorical-6': '#964AC0'
  'chart-categorical-7': '#42B2D7'
  'chart-categorical-8': '#BD5B00'
  'chart-lime-bold': '#6A9A23'
  'chart-lime-bolder': '#5B7F24'
  'chart-lime-boldest': '#4C6B1F'
  'chart-neutral': '#8C8F97'
  'chart-neutral-hovered': '#7D818A'
  'chart-red-bold': '#F15B50'
  'chart-red-bolder': '#E2483D'
  'chart-red-boldest': '#AE2E24'
  'chart-orange-bold': '#E06C00'
  'chart-orange-bolder': '#BD5B00'
  'chart-orange-boldest': '#7A3B00'
  'chart-yellow-bold': '#B38600'
  'chart-yellow-bolder': '#946F00'
  'chart-yellow-boldest': '#7F5F01'
  'chart-green-bold': '#22A06B'
  'chart-green-bolder': '#1F845A'
  'chart-green-boldest': '#216E4E'
  'chart-teal-bold': '#2898BD'
  'chart-teal-bolder': '#227D9B'
  'chart-teal-boldest': '#206A83'
  'chart-blue-bold': '#4688EC'
  'chart-blue-bolder': '#357DE8'
  'chart-blue-boldest': '#1558BC'
  'chart-purple-bold': '#BF63F3'
  'chart-purple-bolder': '#AF59E1'
  'chart-purple-boldest': '#803FA5'
  'chart-magenta-bold': '#DA62AC'
  'chart-magenta-bolder': '#CD519D'
  'chart-magenta-boldest': '#943D73'
  'chart-gray-bold': '#8C8F97'
  'chart-gray-bolder': '#7D818A'
  'chart-gray-boldest': '#505258'
  'chart-brand': '#357DE8'
  'chart-danger': '#E2483D'
  'chart-danger-bold': '#872821'
  'chart-warning': '#F68909'
  'chart-warning-bold': '#BD5B00'
  'chart-success': '#82B536'
  'chart-success-bold': '#5B7F24'
  'chart-discovery': '#BF63F3'
  'chart-discovery-bold': '#803FA5'
  'chart-information': '#357DE8'
  'chart-information-bold': '#1558BC'
  'interaction-hovered': '#00000029'
  'interaction-pressed': '#00000052'
  'skeleton': '#0515240F'
  'skeleton-subtle': '#17171708'
  'blanket': '#050C1F75'
  'blanket-selected': '#388BFF14'
  'blanket-danger': '#EF5C4814'
  'rovo-background-brand-bold': '#000000'
  'rovo-background-brand-bold-hovered': '#1E1F21'
  'rovo-background-brand-bold-pressed': '#292A2E'
  'rovo-border-lime': '#6A9A23'
  'rovo-border-saffron': '#FCA700'
  'rovo-border-blue': '#1868DB'
  'rovo-border-purple': '#AF59E1'
  'rovo-icon-lime': '#6A9A23'
  'rovo-icon-saffron': '#FCA700'
  'rovo-icon-blue': '#1868DB'
  'rovo-icon-purple': '#AF59E1'
typography:
  'heading-xxlarge':
    fontFamily: 'Atlassian Sans'
    fontSize: '2rem'
    fontWeight: 653
    lineHeight: '2.25rem'
  'heading-xlarge':
    fontFamily: 'Atlassian Sans'
    fontSize: '1.75rem'
    fontWeight: 653
    lineHeight: '2rem'
  'heading-large':
    fontFamily: 'Atlassian Sans'
    fontSize: '1.5rem'
    fontWeight: 653
    lineHeight: '1.75rem'
  'heading-medium':
    fontFamily: 'Atlassian Sans'
    fontSize: '1.25rem'
    fontWeight: 653
    lineHeight: '1.5rem'
  'heading-small':
    fontFamily: 'Atlassian Sans'
    fontSize: '1rem'
    fontWeight: 653
    lineHeight: '1.25rem'
  'heading-xsmall':
    fontFamily: 'Atlassian Sans'
    fontSize: '0.875rem'
    fontWeight: 653
    lineHeight: '1.25rem'
  'heading-xxsmall':
    fontFamily: 'Atlassian Sans'
    fontSize: '0.75rem'
    fontWeight: 653
    lineHeight: '1rem'
  'body-large':
    fontFamily: 'Atlassian Sans'
    fontSize: '1rem'
    fontWeight: 400
    lineHeight: '1.5rem'
  'body':
    fontFamily: 'Atlassian Sans'
    fontSize: '0.875rem'
    fontWeight: 400
    lineHeight: '1.25rem'
  'body-small':
    fontFamily: 'Atlassian Sans'
    fontSize: '0.75rem'
    fontWeight: 400
    lineHeight: '1rem'
  'metric-large':
    fontFamily: 'Atlassian Sans'
    fontSize: '1.75rem'
    fontWeight: 653
    lineHeight: '2rem'
  'metric-medium':
    fontFamily: 'Atlassian Sans'
    fontSize: '1.5rem'
    fontWeight: 653
    lineHeight: '1.75rem'
  'metric-small':
    fontFamily: 'Atlassian Sans'
    fontSize: '1rem'
    fontWeight: 653
    lineHeight: '1.25rem'
  'code':
    fontFamily: 'Atlassian Mono'
    fontSize: '0.875em'
    fontWeight: 400
    lineHeight: '1'
  'weight-regular':
    fontWeight: 400
  'weight-medium':
    fontWeight: 500
  'weight-semibold':
    fontWeight: 600
  'weight-bold':
    fontWeight: 653
  'family-heading':
    fontFamily: 'Atlassian Sans'
  'family-body':
    fontFamily: 'Atlassian Sans'
  'family-code':
    fontFamily: 'Atlassian Mono'
  'family-brand-heading':
    fontFamily: 'Charlie Display'
  'family-brand-body':
    fontFamily: 'Charlie Text'
rounded:
  'xsmall': '0.125rem'
  'small': '0.25rem'
  'medium': '0.375rem'
  'large': '0.5rem'
  'xlarge': '0.75rem'
  'xxlarge': '1rem'
  'full': '624.9375rem'
  'tile': '25%'
spacing:
  '0': '0rem'
  '025': '0.125rem'
  '050': '0.25rem'
  '075': '0.375rem'
  '100': '0.5rem'
  '150': '0.75rem'
  '200': '1rem'
  '250': '1.25rem'
  '300': '1.5rem'
  '400': '2rem'
  '500': '2.5rem'
  '600': '3rem'
  '800': '4rem'
  '1000': '5rem'
  'negative-025': '-0.125rem'
  'negative-050': '-0.25rem'
  'negative-075': '-0.375rem'
  'negative-100': '-0.5rem'
  'negative-150': '-0.75rem'
  'negative-200': '-1rem'
  'negative-250': '-1.25rem'
  'negative-300': '-1.5rem'
  'negative-400': '-2rem'
borders:
  'width-default': '0.0625rem'
  'width-selected': '0.125rem'
  'width-focused': '0.125rem'
surfaces:
  'default':
    backgroundColor: '#FFFFFF'
  'default-hovered':
    backgroundColor: '#F0F1F2'
  'default-pressed':
    backgroundColor: '#DDDEE1'
  'sunken':
    backgroundColor: '#F8F8F8'
  'raised':
    backgroundColor: '#FFFFFF'
    shadow: '0px 1px 1px #1E1F2140, 0px 0px 1px #1E1F214F'
  'raised-hovered':
    backgroundColor: '#F0F1F2'
  'raised-pressed':
    backgroundColor: '#DDDEE1'
  'overlay':
    backgroundColor: '#FFFFFF'
    shadow: '0px 8px 12px #1E1F2126, 0px 0px 1px #1E1F214F'
  'overlay-hovered':
    backgroundColor: '#F0F1F2'
  'overlay-pressed':
    backgroundColor: '#DDDEE1'
  'overflow':
    shadow: '0px 0px 8px #1E1F2129, 0px 0px 1px #1E1F211F'
    perimeter: '#1E1F211F'
    spread: '#1E1F2129'
  'container':
    backgroundColor: '#17171708'
  'container-hovered':
    backgroundColor: '#0515240F'
  'container-pressed':
    backgroundColor: '#0B120E24'
motion:
  duration:
    'instant': '0ms'
    'xxshort': '50ms'
    'xshort': '100ms'
    'short': '150ms'
    'medium': '200ms'
    'long': '250ms'
    'xlong': '400ms'
    'xxlong': '600ms'
  easing:
    'in-practical': 'cubic-bezier(0.6, 0, 0.8, 0.6)'
    'inout-bold': 'cubic-bezier(0.4, 0, 0, 1)'
    'out-practical': 'cubic-bezier(0.4, 1, 0.6, 1)'
    'out-bold': 'cubic-bezier(0, 0.4, 0, 1)'
    'spring':
      'linear(0, 0.021, 0.058, 0.107, 0.164, 0.227, 0.292, 0.359, 0.425, 0.49, 0.552, 0.61, 0.664,
      0.714, 0.759, 0.8, 0.837, 0.869, 0.898, 0.922, 0.943, 0.961, 0.976, 0.988, 0.998, 1.006,
      1.013, 1.017, 1.02, 1.023, 1.024, 1.024, 1.024, 1.024, 1.023, 1.022, 1.02, 1.019, 1.017,
      1.015, 1.014, 1.012, 1.011, 1.009, 1.008, 1.007, 1.006, 1.005, 1.004, 1.003, 1.002, 1.002,
      1.001, 1.001, 1.001, 1, 1, 1, 1, 1, 0.999, 0.999, 0.999, 0.999, 1)'
components:
  button-default:
    backgroundColor: '{colors.background-neutral-subtle}'
    textColor: '{colors.text-subtle}'
    borderColor: '{colors.border}'
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.medium}'
    typography: '{typography.body}'
    fontWeight: '{weight.medium}'
    paddingBlock: '{spacing.075}'
    paddingInline: '{spacing.150}'
    columnGap: '{spacing.075}'
  button-default-hovered:
    backgroundColor: '{colors.background-neutral-subtle-hovered}'
  button-default-pressed:
    backgroundColor: '{colors.background-neutral-subtle-pressed}'
  button-selected:
    backgroundColor: '{colors.background-selected}'
    textColor: '{colors.text-selected}'
    borderColor: '{colors.border-selected}'
  button-disabled:
    backgroundColor: transparent
    textColor: '{colors.text-disabled}'
    borderColor: '{colors.border-disabled}'
  button-primary:
    backgroundColor: '{colors.background-brand-bold}'
    textColor: '{colors.text-inverse}'
  button-subtle:
    backgroundColor: '{colors.background-neutral-subtle}'
    textColor: '{colors.text-subtle}'
  button-warning:
    backgroundColor: '{colors.background-warning-bold}'
    textColor: '{colors.text-warning-inverse}'
  button-danger:
    backgroundColor: '{colors.background-danger-bold}'
    textColor: '{colors.text-inverse}'
  button-discovery:
    backgroundColor: '{colors.background-discovery-bold}'
    textColor: '{colors.text-inverse}'
  button-compact:
    paddingBlock: '{spacing.025}'
    paddingInline: '{spacing.100}'
    typography: '{typography.body}'
  icon-button:
    backgroundColor: '{colors.background-neutral-subtle}'
    textColor: '{colors.text-subtle}'
    borderColor: '{colors.border}'
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.medium}'
    width: 2rem
    height: 2rem
    padding: '{spacing.0}'
  icon-button-circle:
    rounded: '{rounded.full}'
  icon-button-compact:
    width: 1.5rem
    height: 1.5rem
  button-group:
    gap: '{spacing.050}'

  textfield-standard:
    backgroundColor: '{colors.background-input}'
    textColor: '{colors.text}'
    borderColor: '{colors.border-input}'
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.medium}'
    typography: '{typography.body}'
    padding: '{spacing.075}'
    placeholderColor: '{colors.text-subtlest}'
  textfield-standard-hovered:
    backgroundColor: '{colors.background-input-hovered}'
  textfield-standard-focused:
    backgroundColor: '{colors.background-input-pressed}'
    borderColor: '{colors.border-focused}'
  textfield-standard-invalid:
    borderColor: '{colors.border-danger}'
  textfield-standard-disabled:
    backgroundColor: '{colors.background-disabled}'
    textColor: '{colors.text-disabled}'
  textfield-subtle:
    backgroundColor: transparent
    textColor: '{colors.text}'
    borderColor: transparent
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.medium}'
    typography: '{typography.body}'
    padding: '{spacing.075}'
    placeholderColor: '{colors.text-subtlest}'
  textfield-subtle-hovered:
    backgroundColor: '{colors.background-input-hovered}'
    borderColor: '{colors.border-input}'
  textfield-subtle-focused:
    backgroundColor: '{colors.background-input-pressed}'
    borderColor: '{colors.border-focused}'
  textfield-none:
    backgroundColor: transparent
    textColor: '{colors.text}'
    borderColor: transparent
    rounded: '{rounded.medium}'
    typography: '{typography.body}'
    padding: '{spacing.075}'
  textfield-compact:
    padding: '{spacing.025}'

  form-label:
    textColor: '{colors.text-subtle}'
    typography: '{typography.body-small}'
  form-helper-message:
    textColor: '{colors.text-subtlest}'
    typography: '{typography.body-small}'
  form-error-message:
    textColor: '{colors.text-danger}'
    typography: '{typography.body-small}'
  form-valid-message:
    textColor: '{colors.text-success}'
    typography: '{typography.body-small}'

  section-message:
    textColor: '{colors.text}'
    titleTypography: '{typography.heading-small}'
    titleFontWeight: '{weight.bold}'
    typography: '{typography.body}'
    rounded: '{rounded.large}'
    padding: '{spacing.200}'
    columnGap: '{spacing.200}'
  section-message-information:
    backgroundColor: '{colors.background-information}'
    iconColor: '{colors.icon-information}'

  popup:
    backgroundColor: '{surfaces.overlay.backgroundColor}'
    shadow: '{surfaces.overlay.shadow}'
    textColor: '{colors.text}'
    rounded: '{rounded.large}'

  tooltip:
    backgroundColor: '{colors.background-neutral-bold}'
    textColor: '{colors.text-inverse}'
    rounded: '{rounded.small}'
    typography: '{typography.body-small}'
    paddingBlock: '{spacing.050}'
    paddingInline: '{spacing.075}'
    maxWidth: 240px
  tooltip-truncate:
    maxWidth: 420px

  link-default:
    textColor: '{colors.link}'
    textDecoration: underline
    rounded: '{rounded.xsmall}'
  link-default-hovered:
    textColor: '{colors.link}'
    textDecoration: none
  link-default-pressed:
    textColor: '{colors.link-pressed}'
  link-default-visited:
    textColor: '{colors.link-visited}'
  link-default-visited-pressed:
    textColor: '{colors.link-visited-pressed}'
  link-subtle:
    textColor: '{colors.text-subtle}'
    textDecoration: none
  link-subtle-hovered:
    textColor: '{colors.text-subtle}'
    textDecoration: underline
  link-subtle-pressed:
    textColor: '{colors.text}'
    textDecoration: underline
  link-inverse:
    textColor: '{colors.text-inverse}'
    textDecoration: underline
  link-inverse-hovered:
    textColor: '{colors.text-inverse}'
    textDecoration: none

  tab-list:
    fontWeight: '{weight.medium}'
    baselineColor: '{colors.border}'
    baselineWidth: '{borders.width-default}'
  tab:
    textColor: '{colors.text-subtle}'
    typography: '{typography.body}'
    rounded: '{rounded.medium}'
    paddingBlock: '{spacing.075}'
    paddingInline: '{spacing.100}'
    underlineColor: '{colors.border}'
    underlineWidth: '{borders.width-selected}'
  tab-hovered:
    textColor: '{colors.text-subtle}'
    underlineColor: '{colors.border}'
  tab-pressed:
    textColor: '{colors.text}'
  tab-selected:
    textColor: '{colors.text-selected}'
    underlineColor: '{colors.border-selected}'

  modal-dialog:
    backgroundColor: '{surfaces.overlay.backgroundColor}'
    shadow: '{surfaces.overlay.shadow}'
    textColor: '{colors.text}'
    rounded: '{rounded.xlarge}'
    widthSmall: 400px
    widthMedium: 600px
    widthLarge: 800px
    widthXLarge: 968px
    blanketColor: '{colors.blanket}'
  modal-header:
    paddingBlockStart: '{spacing.300}'
    paddingBlockEnd: '{spacing.200}'
    paddingInline: '{spacing.300}'
    titleTypography: '{typography.heading-medium}'
  modal-body:
    typography: '{typography.body}'
    paddingBlock: '{spacing.025}'
    paddingInline: '{spacing.300}'
  modal-footer:
    paddingBlockStart: '{spacing.200}'
    paddingBlockEnd: '{spacing.300}'
    paddingInline: '{spacing.300}'
    columnGap: '{spacing.100}'

  toggle:
    backgroundColor: '{colors.background-neutral-bold}'
    thumbColor: '{colors.icon-inverse}'
    rounded: '{rounded.full}'
    width: '{spacing.400}'
    height: '{spacing.200}'
    thumbSize: 12px
    thumbTravel: '{spacing.200}'
  toggle-large:
    width: '{spacing.500}'
    height: '{spacing.250}'
    thumbSize: 16px
    thumbTravel: '{spacing.250}'
  toggle-checked:
    backgroundColor: '{colors.background-success-bold}'
  toggle-checked-hovered:
    backgroundColor: '{colors.background-success-bold-hovered}'
  toggle-hovered:
    backgroundColor: '{colors.background-neutral-bold-hovered}'
  toggle-disabled:
    backgroundColor: '{colors.background-disabled}'
    thumbColor: '{colors.icon-disabled}'

  radio:
    backgroundColor: '{colors.background-input}'
    borderColor: '{colors.border-input}'
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.full}'
    size: 16px
    hitTargetSize: 24px
    labelTypography: '{typography.body}'
    labelColor: '{colors.text}'
    labelPaddingBlock: '{spacing.025}'
    labelPaddingInline: '{spacing.050}'
  radio-hovered:
    backgroundColor: '{colors.background-input-hovered}'
  radio-pressed:
    backgroundColor: '{colors.background-input-pressed}'
  radio-selected:
    backgroundColor: '{colors.background-selected-bold}'
    borderColor: '{colors.background-selected-bold}'
    dotColor: '{colors.icon-inverse}'
    dotSize: 6px
  radio-selected-hovered:
    backgroundColor: '{colors.background-selected-bold-hovered}'
    borderColor: '{colors.background-selected-bold-hovered}'
  radio-disabled:
    backgroundColor: '{colors.background-disabled}'
    borderColor: '{colors.border-disabled}'
    dotColor: '{colors.icon-disabled}'
    labelColor: '{colors.text-disabled}'
  radio-invalid:
    borderColor: '{colors.icon-danger}'

  checkbox:
    backgroundColor: '{colors.background-input}'
    borderColor: '{colors.border-input}'
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.small}'
    size: 16px
    tickColor: '{surfaces.default.backgroundColor}'
    labelTypography: '{typography.body}'
    labelColor: '{colors.text}'
    labelGap: '{spacing.050}'
  checkbox-hovered:
    backgroundColor: '{colors.background-input-hovered}'
  checkbox-pressed:
    backgroundColor: '{colors.background-input-pressed}'
    borderColor: '{colors.border}'
  checkbox-checked:
    backgroundColor: '{colors.background-selected-bold}'
    borderColor: '{colors.background-selected-bold}'
    tickColor: '{colors.icon-inverse}'
  checkbox-checked-hovered:
    backgroundColor: '{colors.background-selected-bold-hovered}'
    borderColor: '{colors.background-selected-bold-hovered}'
  checkbox-disabled:
    backgroundColor: '{colors.background-disabled}'
    borderColor: '{colors.background-disabled}'
    tickColor: '{colors.icon-disabled}'
    labelColor: '{colors.text-disabled}'
  checkbox-invalid:
    borderColor: '{colors.border-danger}'

  avatar:
    rounded: '{rounded.full}'
    presenceBackground: '{surfaces.default.backgroundColor}'
    stackedRingColor: '{surfaces.default.backgroundColor}'
    stackedRingWidth: 2px
    hoveredOverlay: '{colors.interaction-hovered}'
    pressedOverlay: '{colors.interaction-pressed}'
    pressedScale: '0.9'
  avatar-xsmall:
    size: 16px
    squareRadius: 2px
  avatar-small:
    size: 24px
    squareRadius: 2px
  avatar-medium:
    size: 32px
    squareRadius: 3px
  avatar-large:
    size: 40px
    squareRadius: 3px
  avatar-xlarge:
    size: 96px
    squareRadius: 6px
  avatar-xxlarge:
    size: 128px
    squareRadius: 12px
  avatar-disabled:
    backgroundColor: '{surfaces.default.backgroundColor}'
    opacity: '0.4'

  avatar-group-stack:
    overlap: '{spacing.100}'
    moreIndicatorGap: '{spacing.050}'
  avatar-group-grid:
    rowGap: '{spacing.100}'
    columnGap: '{spacing.050}'

  spinner:
    color: '{colors.icon-subtle}'
    strokeWidth: 1.5px
    strokeDasharray: '60'
    rotateDuration: 0.86s
    rotateIterationCount: infinite
    rotateTimingFunction: 'cubic-bezier(0.4, 0.15, 0.6, 0.85)'
    rotateTransformOrigin: center
    loadInDuration: 1s
    loadInTimingFunction: ease-in-out
    loadInFillMode: forwards
  spinner-inverse:
    color: '{colors.icon-inverse}'
  spinner-xsmall:
    size: 12px
  spinner-small:
    size: 16px
  spinner-medium:
    size: 24px
  spinner-large:
    size: 48px
  spinner-xlarge:
    size: 96px

  tag:
    backgroundColor: transparent
    textColor: '{colors.text}'
    borderColor: '{colors.border-accent-gray}'
    iconColor: '{colors.icon-accent-gray}'
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.small}'
    typography: '{typography.body-small}'
    paddingBlock: '{spacing.025}'
    paddingInline: '{spacing.025}'
    columnGap: '{spacing.050}'
  tag-hovered:
    backgroundColor: transparent
  tag-pressed:
    backgroundColor: transparent
  tag-gray:
    backgroundColor: transparent
    borderColor: '{colors.border-accent-gray}'
    iconColor: '{colors.icon-accent-gray}'

  badge:
    backgroundColor: '{colors.background-accent-gray-subtler}'
    textColor: '{colors.text}'
    minWidth: '{spacing.300}'
    rounded: '{rounded.xsmall}'
    typography: '{typography.body-small}'
    paddingInline: '{spacing.050}'
    paddingBlock: 0
  badge-success:
    backgroundColor: '{colors.background-success-subtler}'
    textColor: '{colors.text-success-bolder}'

  lozenge:
    backgroundColor: '{colors.background-neutral}'
    textColor: '{colors.text}'
    iconBase: '{colors.icon-subtlest}'
    borderBase: '{colors.border-bold}'
    borderWidth: '{borders.width-default}'
    rounded: '{rounded.small}'
    typography: '{typography.body-small}'
    fontWeight: '{weight.regular}'
    height: 1.25rem
    paddingBlock: '{spacing.025}'
    paddingInline: '{spacing.050}'
    iconLightnessFactor:
      light:
        resting: '0.88'
        hovered: '0.8'
        pressed: '0.7'
        selected: '0.7'
      dark:
        resting: '1.0'
        hovered: '1.15'
        pressed: '1.37'
        selected: '1.37'
    borderLightnessFactor:
      light:
        resting: '1.33'
        hovered: '1.2'
        pressed: '1.08'
        selected: '1.08'
      dark:
        resting: '0.7'
        hovered: '0.8'
        pressed: '0.9'
        selected: '0.9'

  lozenge-spacious:
    minHeight: 2rem
    rounded: '{rounded.medium}'
    typography: '{typography.body}'
    fontWeight: '{weight.medium}'
    paddingBlock: '{spacing.050}'
    paddingInline: '{spacing.150}'
  lozenge-selected:
    textColor: '{colors.text-selected}'
  lozenge-success:
    backgroundColor: '{colors.background-success-subtler}'
    textColor: '{colors.text-success-bolder}'
    iconBase: '{colors.icon-success}'
    borderBase: '{colors.border-success}'

  table-head:
    backgroundColor: '{surfaces.default.backgroundColor}'
    borderBlockEndColor: '{colors.border}'
    borderBlockEndWidth: '{borders.width-selected}'
  table-head-cell:
    textColor: '{colors.text-subtle}'
    typography: '{typography.body-small}'
    fontWeight: '{weight.bold}'
    paddingBlock: '{spacing.050}'
    paddingInline: '{spacing.100}'
    borderBlockEndColor: '{colors.border}'
    borderBlockEndWidth: '{borders.width-selected}'
  table-row:
    backgroundColor: '{colors.background-neutral-subtle}'
    borderBlockEndColor: '{colors.border}'
    borderBlockEndWidth: '{borders.width-default}'
  table-row-hovered:
    backgroundColor: '{colors.background-neutral-subtle-hovered}'
  table-row-selected:
    backgroundColor: '{colors.background-selected}'
  table-row-selected-hovered:
    backgroundColor: '{colors.background-selected-hovered}'
  table-cell:
    textColor: '{colors.text}'
    typography: '{typography.body}'
    paddingBlock: '{spacing.050}'
    paddingInline: '{spacing.100}'
  table-compact:
    paddingBlock: '{spacing.025}'
    paddingInline: '{spacing.075}'

  code:
    backgroundColor: '{colors.background-neutral}'
    textColor: '{colors.text}'
    rounded: '{rounded.small}'
    typography: '{typography.code}'
    paddingBlock: '{spacing.025}'
    paddingInline: 0.5ch

  code-block:
    backgroundColor: '{colors.background-neutral}'
    textColor: '{colors.text}'
    rounded: '{rounded.large}'
    typography: '{typography.code}'
    paddingBlock: '{spacing.100}'
    paddingInline: '{spacing.100}'
    lineHeight: 20px
    lineNumberColor: '{colors.text-subtlest}'
    lineNumberBackground: '{colors.background-neutral}'
  code-block-highlight:
    backgroundColor: '{colors.background-neutral}'
    accentColor: '{colors.border-focused}'
    accentWidth: 4px
---

# Atlassian DESIGN.md

> A portable, token-first manifest for producing anything that should look like it belongs at
> Atlassian — product UI, slides, charts, dashboards, onboarding screens, or marketing surfaces.

Everything needed to build UI is in this file: **YAML above** (every color hex, type scale, spacing,
corner radii, border widths, and a few control "recipes") plus **this prose** (how the pieces fit
together). Rules use RFC 2119: MUST, MUST NOT, SHOULD, MAY.

For implementation-level references — per-component API bindings, dark/light token catalogs, prompt
guidance, and linting rules — load the Atlassian Design System MCP server or
**atlassian-design-system** skill.

### Table of contents

**Canonical (spec-shaped):** [Overview](#overview) · [Colors](#colors) · [Typography](#typography) ·
[Layout](#layout) · [Elevation & Depth](#elevation--depth) · [Shapes](#shapes) ·
[Components](#components) · [Do's and Don'ts](#dos-and-donts)

**Atlassian extensions:** [Icons](#icons) · [Motion](#motion) · [Voice and tone](#voice-and-tone) ·
[Accessibility](#accessibility) · [Responsive behaviour](#responsive-behaviour)

---

### Related

- [Atlassian Design System](https://atlassian.design) — canonical token catalog, component APIs, and
  foundations.
- **atlassian-design-system** skill — progressive-disclosure skill for token/component lookup and
  ADS MCP usage when you have an ADS-capable stack.
- ADS MCP tools — direct token, component, and linting integrations where available.
- ADS ESLint plugins (design system and UI styling standards) — enforcement layer for CI in repos
  that wire them up.
- Full-length `DESIGN.md` — per-component API bindings, dark-anchor palettes, agent prompt guide,
  and design-rigor checks.

---

## Overview

### About this file

> A portable, token-first manifest for producing anything that should look like it belongs at
> Atlassian — product UI, slides, charts, dashboards, onboarding screens, or marketing surfaces.

Everything needed to build UI is in this file: **YAML above** (every color hex, type scale, spacing,
corner radii, border widths, and a few control "recipes") plus **this prose** (how the pieces fit
together). Rules use RFC 2119: MUST, MUST NOT, SHOULD, MAY.

This file is for generating UI in the style of Atlassian's system, not for use generating production
screens inside Atlassian apps, and focuses on design principles and intention, rather than specific
implementation details. Use the Atlassian Design System MCP server, or the ADS `Skills.md` file, to
get detailed, token-efficient references for how to implement Atlassian UI using the ADS tokens and
component libraries, as well as information on coding standards.

This file is a succinct canonical standalone manifest. For deeper implementation detail, load the
Atlassian Design System MCP server or the `atlassian-design-system` skill.

The `DESIGN.md` spec is still in alpha, and this file diverges from the spec in a few areas:

- Some tokens have transparency, which is required in the ADS token system
- Some components reference properties beyond the set in the current standard to encapsulate more of
  the behaviour of the component

### Table of contents

**Canonical (spec-shaped):** [Overview](#overview) · [Colors](#colors) · [Typography](#typography) ·
[Layout](#layout) · [Elevation & Depth](#elevation--depth) · [Shapes](#shapes) ·
[Components](#components) · [Do's and Don'ts](#dos-and-donts)

**Atlassian extensions:** [Icons](#icons) · [Motion](#motion) · [Voice and tone](#voice-and-tone) ·
[Accessibility](#accessibility) · [Responsive behaviour](#responsive-behaviour)

### Brand & Style

Atlassian product UI is **neutral-dominant with restrained saturation, built on an 8px rhythm, a
t-shirt radius scale, and a four-plane elevation model.** Surfaces are calm; color carries meaning;
depth is earned, not decorative. Where brand expression is needed, a single layer of Charlie
typography and logo artwork is applied over an otherwise product-native canvas.

#### Atmosphere rules

- **MUST** default to neutral backgrounds (`surface`, `background-neutral`) for the ~90% of the
  canvas that is not communicating meaning.
- **MUST** reserve saturated color for one of: semantic roles (brand, danger, warning, success,
  information, discovery), decorative accents (tags, file types, avatar chips), or data
  visualization.
- **MUST** compose layouts on the 8px grid via the `spacing` scale (`space-100`, `space-200`, etc. —
  see [Layout](#layout)).
- **MUST** pair every elevated surface with its matching shadow token (see
  [Elevation & Depth](#elevation--depth)).
- **MUST NOT** imitate Material's depth theatre (floating cards everywhere), generic Shadcn/Tailwind
  neutral gradients, or marketing site branding; this system is for practical product UI.
- **SHOULD** prefer whitespace and borders for grouping before reaching for elevation.
- **SHOULD** let the canvas be mostly quiet so that color and motion (when used) carry actual
  signal.

#### Brand vs product

- **Atlassian Sans** is the product typeface for every screen, button, table, and form (see
  [Typography](#typography)).
- **Charlie Display / Charlie Text** are reserved for marketing surfaces and hero moments — never
  used in settings pages, dashboards, or dense product chrome.
- The **Atlassian wordmark and product lockups** belong on marketing surfaces, sign-in screens, and
  email — never inline in product chrome as a decorative flourish. When a logo is needed in-product,
  use the small monochrome glyph at icon-size, not the full wordmark.

#### Reference points

- **Aligned with:** IBM Carbon (token-first discipline), Linear (restraint), GitHub Primer (neutral
  backbone with semantic accents).
- **Not aligned with:** Material Design (heavier elevation, broader saturation), Shadcn/Tailwind
  defaults (greyscale gradients, generic radius), Fluent (heavier acrylic/blur effects).

---

## Colors

ADS has four kinds of color, and they are not interchangeable:

1. **Neutrals and surfaces** — backbone for 80–90% of the canvas.
2. **Semantic roles** — meaning carriers (brand, danger, warning, success, information, discovery).
3. **Accent ramps** — decoration only (tags, file types, avatar chips).
4. **Chart colors** — data visualization only.

Refer to tokens by their YAML key in prose and recipes; emit literal hex in HTML/CSS. Hex values
below reflect this build's theme.

### 1) Neutrals and surfaces

| Token                   | Hex                   | Use                                                                                   |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------------- |
| `surface`               | `#FFFFFF`             | Page / card fill                                                                      |
| `surface-sunken`        | `#F8F8F8`             | **Inside** a page: wells, columns, grouped panels — not the outermost page background |
| `surface-raised`        | `#FFFFFF`             | Movable card — pair with `shadow-raised`                                              |
| `surface-overlay`       | `#FFFFFF`             | Modal, popover, toast shell — pair with `shadow-overlay`                              |
| `text`                  | `#292A2E`             | All paragraph-style copy                                                              |
| `text-subtle`           | `#505258`             | Labels, metadata — **not** long prose                                                 |
| `text-subtlest`         | `#6B6E76`             | Placeholders, hints                                                                   |
| `border`                | `#0B120E24`           | Hairline dividers (alpha)                                                             |
| `border-bold`           | `#7D818A`             | Stronger divider                                                                      |
| `border-input`          | `#8C8F97`             | Field outline                                                                         |
| `border-focused`        | `#4688EC`             | 2px focus ring color                                                                  |
| `link` / `link-pressed` | `#1868DB` / `#1558BC` | Text links                                                                            |

The four surface planes and their paired shadows are documented in
[Elevation & Depth](#elevation--depth).

### 2) Semantic roles — _they mean something to the user_

These answer: "What state or message is this?" Examples: **danger** (destructive action, error),
**warning** (caution), **success** (done), **information** (neutral notice), **discovery**
(new/beta), **brand** (primary company action).

- Names always use whole words: `background-danger-bold`, `text-success`, `icon-information`, etc.
- Each role has the same four anchors — substitute the role to get the token name: `text-<role>`,
  `icon-<role>`, `border-<role>`, and the filled `background-<role>-bold`. Hex values live in the
  YAML.
- **MUST** treat `success` as a **semantic role token family**, not the decorative `accent-green`
  family. In this system, success appears as a lime colour, but should always be referenced using a
  success token. `accent-green` as a success substitute is a drift bug.
- **MUST** pick the role that matches the user meaning (a delete confirmation is **danger**, not
  **warning**).
- On **bold** filled backgrounds (`*-bold`), text is usually `text-inverse`. **Exception:**
  `background-warning-bold` is light yellow, so readable text on it is `text-warning-inverse` /
  `icon-warning-inverse` (dark — not white).
- For **inline messages** (tinted background + icon + title + body): use semantic **background** +
  **icon-** role tokens, but keep **body copy** in neutral **`text`** or **`text-subtle`**. Do
  **not** tint paragraphs blue on a blue information panel — that fails both design and contrast
  intuition.

### 3) Accent ramps — _pure decoration, not status_

These are the **`background-accent-*`**, **`text-accent-*`**, **`icon-accent-*`**,
**`border-accent-*`** keys.

- **Ten hues:** `lime`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `magenta`,
  `gray`.
- **Four lightness steps** on backgrounds (pale → strong): `subtlest` → `subtler` → `subtle` →
  `bolder`.
- **Pairing rule:** on `subtlest` / `subtler` backgrounds, use `text-accent-<hue>` or
  `text-accent-<hue>-bolder`. On `subtle` use `text-accent-<hue>-bolder`. On `bolder` treat it like
  any other strong fill and use `text-inverse`. The leading icon, when there is one, uses
  `icon-accent-<hue>`. Substitute the hue and the same shape works for every ramp.
- **MUST NOT** use accent ramps to fake semantics — `background-accent-red-*` is not a substitute
  for `background-danger-*`. Accents are for tags, file-type chips, avatars, decorative labels — not
  "error".

### 4) Chart colors — _only for data visualization_

Three patterns appear in `colors`:

1. **`chart-categorical-1` … `chart-categorical-8`** — Eight distinct hues for **up to eight
   different data series** on one chart (bar segments, lines, pie slices). Use them **in order**
   when you do not have a reason to remap: series 1 → token 1, etc. The hex per index is in the
   YAML.
2. **`chart-<hue>-bold` / `chart-<hue>-bolder` / `chart-<hue>-boldest`** — For **one hue** you get
   three steps (lighter → darker) to show value tiers or emphasis inside a single colour family.
   Example for yellow: **`chart-yellow-bold`** `#B38600`, **`chart-yellow-bolder`** `#946F00`,
   **`chart-yellow-boldest`** `#7F5F01`.
3. **Semantic chart tokens** — when a series should read as a status:

| Token                                          | When to use                                 |
| ---------------------------------------------- | ------------------------------------------- |
| `chart-brand`                                  | Primary metric line                         |
| `chart-success` / `chart-success-bold`         | Completed, on-track, positive status        |
| `chart-warning` / `chart-warning-bold`         | Risk status, medium priority                |
| `chart-danger` / `chart-danger-bold`           | Negative status, off-track, high priority   |
| `chart-information` / `chart-information-bold` | Low priority, in-progress                   |
| `chart-discovery` / `chart-discovery-bold`     | New / experimental                          |
| `chart-neutral`                                | "To do" status, untracked, neutral baseline |

**MUST** add non-color cues (patterns, labels, shapes) so charts still read for colorblind users, or
if printed in greyscale.

---

## Typography

### Families

- **Atlassian Sans** (`family-body` / `family-heading`) — product UI: every screen, button, form,
  table, dashboard. Based on Inter
- **Atlassian Mono** (`family-code`) — code blocks, inline code, monospace numerics. Based on
  Jetbrains Mono.
- **Charlie Display / Charlie Text** (`family-brand-heading` / `family-brand-body`) — **marketing
  and brand surfaces only**. Never in product settings or dense chrome.
- **MUST NOT** introduce third-party fonts (Inter, Geist, SF Pro, Roboto). The system fallback stack
  already covers platforms where Atlassian Sans is unavailable

### Heading scale

Use plain `<h1>`–`<h6>` (one H1 per page, never skip levels) with the size + weight pair from the
`typography:` YAML. Pick the size that fits the surface — never hand-author headings outside the
scale, and never make a heading lighter or heavier than the token.

### Body scale

- **`body`** — default for component text; the single most common typography choice in product UI.
- **`body-large`** — long-form content (blog, documentation bodies).
- **`body-small`** — fine print, helper text, lozenges/tags/badges, table column headers. Use
  sparingly.

Rules:

- **MUST** render paragraphs, list items, descriptions, and any continuous prose in `text`. Using
  `text-subtle` for body copy to "differentiate it from headings" is a drift pattern — size and
  weight already provide the hierarchy.
- Reserve `text-subtle` for secondary metadata (field labels, captions, bylines, nav items) and
  `text-subtlest` for placeholders and helper text.

### Weights

- `weight-regular` — default body.
- `weight-medium` — text beside icons (buttons, nav items) — the "safe" bold against icon strokes.
- `weight-bold` — rare emphasis (lozenges, headings).
- **MUST** set font weight via these tokens, not arbitrary numerics like `fontWeight: 700`.

### Case

- **MUST** use **sentence case** for every piece of user-visible text in product UI: titles,
  headings, buttons, menu items, tab labels, tooltips, flag titles, empty-state headings, table
  column headers, form labels — everything.
- **MUST** capitalize proper nouns (people, company names, product names: _Jira_, _Confluence_,
  _Trello_, _Atlassian_).
- **MUST NOT** use Title Case ("Create Work Item") — correct to sentence case ("Create work item")
  on sight. This is one of the most common mistakes LLMs create when generating Atlassian UI.
- **MUST NOT** use ALL CAPS or `letter-spacing`-stretched uppercase anywhere — including eyebrows,
  lozenges, tags, badges, and table column headers. There are no exemptions.
- Atlassian does **not** use the "eyebrow" / "overline" pattern (small label above a heading). If a
  categorical label is genuinely needed, use a lozenge (semantic) or tag (decorative) beside the
  heading, or a byline under the heading.

### Translation

- **MUST** treat every user-visible string as translatable. Never hard-code English; never
  concatenate sentence fragments — pluralisation, gender, and word order vary by locale.
- **MUST** leave room for translated strings to grow ~30% longer than the English source without
  breaking layout or truncating mid-word. Headings, button labels, and table column headers are the
  usual victims.

---

## Layout

Atlassian spacing is an **8px-base** system. Every distance on the canvas — padding, margin, gap,
inset — **MUST** land on a token step from the `spacing:` YAML scale. No off-grid `13px`,
`10px 14px`, or arbitrary `rem`.

### Picking a step

The scale runs from `space-0` through `space-1000`; the full rem/px values live in the YAML. As a
decision aid: tight component interiors land at `space-0`…`space-100`, roomier component interiors
at `space-150`…`space-300`, page-level layout at `space-400` and up. Negative steps mirror the
positive scale for overlap and bleed.

### Principles

- **MUST** express relationships via proximity — things that belong together sit closer
  (small/medium gaps); unrelated things sit further apart (medium/large gaps).
- **MUST** use consistent spacing within repeating elements (list items, table rows, card grids).
  Consistency creates the visual rhythm that makes scanning fast.
- **MUST** vary the step to express hierarchy — e.g. `space-100` / `space-150` between a label and
  its field, `space-300` / `space-400` between unrelated blocks. The same `space-200` on every edge
  flattens hierarchy.
- **SHOULD** use a larger step around more important blocks (bigger surrounding space = more
  important).
- **MAY** make optical adjustments (±one step) when strict tokens produce a visual imbalance — but
  the starting point is always a token, not a pixel measurement.

### Implementation

- Emit spacing in the rem value the chosen token resolves to. **MUST NOT** use off-rail pixel values
  such as `gap: 13px` or `padding: 10px 14px` — round to the nearest token step.
- For multi-column page layouts, use a 12-column grid with `space-300` gutters and `space-400` page
  padding. Compose with flex/grid on `space-*` rhythm rather than fixed widths.

---

## Elevation & Depth

Atlassian elevation is a **four-plane** system plus an overflow treatment. Each plane has a specific
purpose; raising or overlaying is an intentional choice, not decoration.

### The four planes

| Plane       | Surface token     | Shadow token     | Use                                                                                                                                                                         |
| ----------- | ----------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default** | `surface`         | —                | The flat canvas. Cards and containers here use borders, not shadows.                                                                                                        |
| **Raised**  | `surface-raised`  | `shadow-raised`  | Movable cards (Trello, Jira board cards). At most one raised region per screen.                                                                                             |
| **Overlay** | `surface-overlay` | `shadow-overlay` | Modals, dialogs, dropdown menus, floating toolbars, flags, popovers, tooltips, spotlight. Overlays can stack on overlays.                                                   |
| **Sunken**  | `surface-sunken`  | —                | Wells that group content (Kanban columns, background panels) **inside** a page whose canvas is already `surface`. Only on the default plane — never stack sunken on raised. |

### Page canvas

- **MUST** use `surface` (`#FFFFFF`) as the page / artifact background. This is the rule for every
  standalone surface — product pages, reports, dashboards, embedded views, email, slides, exported
  documents. `surface` _is_ the canvas.
- **MUST NOT** use `surface-sunken` as the page background to create contrast against cards. Sunken
  is a **well inside** a page (Kanban columns, a filters rail, a conversation thread) — not the
  outermost surface. "Grey page, white cards" is the common drift pattern; the Atlassian pattern is
  "white page, bordered cards, optional sunken wells inside."
- To create visual separation between a card and its container without switching surface tokens, use
  `border` + `space-200` / `space-300` padding, or raise the card to `surface-raised` +
  `shadow-raised`. Do not darken the canvas.

### Pairing rules

- **MUST** pair every `surface-raised` with `shadow-raised`, and every `surface-overlay` with
  `shadow-overlay`. Mixing shadows across planes is a bug; the shadow recipes live in the YAML so
  callers never hand-author `box-shadow` values.
- **MUST** prefer the border-on-scroll treatment (`border` at the clip edge) as the default scroll
  cue; reach for `shadow-overflow` only when borders would be missed (horizontal table scroll, modal
  body scroll).
- **MUST** stack overlays along the planes — navigation under inline dialogs under popups under
  modals under flags under tooltips. Don't invent new z-index buckets; reuse the existing plane that
  matches your overlay's purpose.

---

## Shapes

### Corner radius

Atlassian uses a t-shirt radius scale, and each size maps to a class of component. **Choose radius
by _what the thing is_, not by taste.**

| Token            | rem      | px   | Component class                                                         |
| ---------------- | -------- | ---- | ----------------------------------------------------------------------- |
| `radius-xsmall`  | 0.125rem | 2px  | Badges, checkboxes, avatar labels, keyboard shortcuts                   |
| `radius-small`   | 0.25rem  | 4px  | Lozenges, tags, timestamps, tooltips, table thumbnails, compact buttons |
| `radius-medium`  | 0.375rem | 6px  | Buttons, inputs, selects, nav items, smart links                        |
| `radius-large`   | 0.5rem   | 8px  | Cards, in-page containers, dropdown menus, floating UI                  |
| `radius-xlarge`  | 0.75rem  | 12px | Modal dialogs, Kanban columns, large containers, tables                 |
| `radius-xxlarge` | 1rem     | 16px | Video players only                                                      |
| `radius-full`    | (pill)   | —    | Avatars, pills, user-related UI, emoji reactions                        |
| `radius-tile`    | 25%      | —    | Tile components only (icon tile, object tile)                           |

Rules:

- **MUST** select radius by the component class above. A button is `radius-medium`; a card is
  `radius-large`; a modal is `radius-xlarge`.
- **MUST** use `radius-full` for circular avatars and pill-shaped elements.
- **MUST NOT** emit arbitrary radius values like `border-radius: 8px` or `10px`. Map to the nearest
  token step.
- **MUST NOT** use `radius-tile` outside the tile component system.

### Focus ring

- **MUST** apply focus rings with `border-width-focused` (2px) and the `border-focused` color.
- **MUST** offset the ring 2px from the component's bounding box.
- **MUST** set the ring's own radius to the component's radius **+ 2px** (so a `radius-medium`
  button gets a focus ring at `radius-large`).
- **MUST NOT** remove focus outlines without providing the same ring contract by hand (width, color,
  radius + 2px).

### Borders

Border widths live on a three-step scale, distinct from spacing and radius. Stroke weight carries
meaning (resting vs selected vs focused) and never drifts into decoration.

| Token                   | rem       | px  | Use                                                                          |
| ----------------------- | --------- | --- | ---------------------------------------------------------------------------- |
| `border-width-default`  | 0.0625rem | 1px | Default hairline: input borders, card outlines, dividers, table row rules.   |
| `border-width-selected` | 0.125rem  | 2px | Selected state: the rail on an active tab/nav row, selected card outline.    |
| `border-width-focused`  | 0.125rem  | 2px | Focus ring on every focusable control (see [Focus ring](#focus-ring) above). |

Rules:

- **MUST** use `border-width-default` (1px) for all resting borders. Anything thicker reads as
  emphasis.
- **MUST** pair `border-width-selected` with the `border-selected` color (and the matching
  text/background tokens) for selected state — never just thicken the resting border.
- **MUST NOT** use thick coloured `border-left` / `border-right` > 1px as the sole callout emphasis
  — use a semantic surface + role icon instead (see [Components](#components) → SectionMessage).
- **MUST NOT** invent fractional widths (e.g. 1.5px) to land between steps. If no step fits, the
  surface treatment is wrong, not the border.

---

## Components

The visual recipe (tokens, padding, radius, typography) for each foundational component is in the
YAML `components:` block at the top of this file — `button-default`, `button-primary`,
`icon-button`, `textfield-standard`, `section-message`, etc. This section covers the **behavioural**
and **layout** rules that YAML can't carry: which variants exist, when to use which, accessibility
contracts, and the anti-patterns to correct on sight.

Theme note: some products may opt into updated shape tokens (larger radii) via the platform shape
theme. Preserve component hierarchy, spacing rhythm, and emphasis order even when corner size
changes.

### Button

Primary inline action control. Use YAML-defined appearances and sizes only (`default`, `primary`,
`subtle`, `warning`, `danger`, `discovery`; default/compact, optional fit-container), and do not
invent additional appearances. Only use compact only in dense surfaces (tables, toolbars) — never as
a default.

- **States:** use YAML state mappings for hover/pressed/selected/disabled/loading; loading and
  focus/invalid emphasis must not cause layout shift.
- **Icons:** leading/trailing icons inherit `currentColor`; do not hardcode icon colors.
- **Hierarchy note:** default button text is intentionally `text-subtle` (not `text`) so primary
  actions keep stronger visual emphasis. Do not "correct" this to full-contrast text.

Rules:

- **MUST** use sentence case, imperative verbs (see [Voice and tone](#voice-and-tone)). "Create work
  item", not "Submit" or "OK".
- **MUST NOT** use `primary` for more than one action per section. If you feel tempted to, one of
  them is probably `default`.
- **MUST NOT** use `warning` or `danger` for CTAs that aren't warning or danger — an orange "Save"
  button is a drift pattern.
- **MUST NOT** hand-author hover/pressed fills — every appearance has matching `*-hovered` /
  `*-pressed` tokens.
- **SHOULD** reach for `subtle` (or a styled link) before inventing a "text-only" appearance.

### IconButton

Square or circular single-icon action for low-emphasis affordances (toolbars, row actions, inline
editors). Supports only `default`, `primary`, `discovery` and `subtle` appearances; it inherits
Button state/token behavior, including `currentColor` icon inheritance.

- **MUST NOT** use IconButton when the action's meaning isn't conveyed by an obvious glyph. Pair the
  icon with a label if the affordance is non-obvious.

### TextField

Single-line text input wrapped by form message primitives (`form-label`, `form-helper-message`,
`form-error-message`, `form-valid-message`). Use YAML-defined appearances/states; use
`subtle`/`none` only when editability is still visually obvious.

- **Responsive density:** below `30rem`, use compact density; from `30rem` and up, use default
  density (exact values in YAML).
- **Slots:** before/after slots are inline with no extra gap; interactive slot content must preserve
  focus order.

Rules:

- **MUST** provide a visible label. Placeholder-as-label is banned; placeholders are not substitutes
  for labels.
- **MUST** use the compact size only in dense surfaces (tables, inline filters) — never as a
  default.
- **MUST NOT** render `subtle` or `none` without a visual affordance that the field is editable
  (hover border, icon, or surrounding chrome).
- **MUST NOT** put interactive elements in the slot-before / slot-after unless you handle focus
  order.

### SectionMessage

Inline page-level status/system notice. Semantic meaning is carried by role background + leading
icon; prose stays neutral. Use `section-message-<semantic-role>` pattern (canonical example:
`section-message-information`).

- **Anatomy:** icon, title, supporting text, optional 1-2 link-style actions.
- **Variant intent:** `information` = neutral context, `warning` = pre-action caution, `error` =
  failure + next action, `success` = completion confirmation, `discovery` = new capability
  announcement.
- **MUST** keep body copy in neutral `text` (not tinted role text). Tinting body text blue on a blue
  information panel is the most common drift pattern; correct on sight.
- **MUST NOT** omit the icon. A SectionMessage without an icon reads as a plain coloured box and
  loses its semantic affordance.
- **MUST NOT** use `error` for "user input didn't validate" — that belongs in `form-error-message`
  beside the field. SectionMessage `error` is for page-level / request-level failures.

### Other components

These components are represented in YAML by token bindings; use this section for intent and usage:

- **Card** — single surface tile. Fill `surface`, hairline `border`, `radius-large`. Use
  `surface-raised` + `shadow-raised` only when movable; otherwise prefer bordered default-surface
  cards.
- **Popup** — transient overlay shell for menus/popovers/date pickers. Wrapper provides
  `surface-overlay` + `shadow-overlay` + radius; padding belongs inside content, not wrapper chrome.
- **Tooltip** — inverted short-form helper label with default/truncate width modes (240px / 420px).
  Keep it non-interactive and keyboard reachable.
- **Link** — default, subtle, and inverse modes are available. Use subtle sparingly; links should
  still be discoverable.
- **Tabs** — 1px baseline plus selected underline marker (`border-width-selected`) aligned to label
  inset, not outer hit target. Keep selected state on text + underline together.
- **Modal / Dialog** — centered overlay with blanket. Width tiers: 400 / 600 / 800 / 968px. Keep
  header/body/footer as separate regions so padding and scroll behavior stay predictable.
- **Toggle** — 32×16 regular and 40×20 large tracks; `toggle.thumbTravel` should be animated as a
  state transition, not jumped. Use success track only when checked. Show a tick/cross icon in the
  track segment not covered by the thumb (tick on the "on" side, cross on the "off" side) so state
  remains legible beyond color.
- **Radio / Checkbox** — 16px controls with 24px hit target. Preserve disabled, invalid, and
  selected token states instead of custom fills. Checkboxes must show the check icon only in checked
  state (and bar icon only for indeterminate); unchecked state has no check glyph.
- **Avatar / AvatarGroup** — circle by default; square uses per-size radii. Stacked groups overlap
  with surface-colored ring separation; grid mode uses tokenized row/column gaps.
- **Spinner** — stroke-based loader with rotate + load-in motion. Preserve motion fields
  `spinner.rotateDuration`, `spinner.rotateTimingFunction`, `spinner.loadInDuration`, and
  `spinner.loadInTimingFunction` instead of bespoke curves.
- **Tag** — decorative classification only (categories, labels), not semantic status. Tags consist
  of an accent-coloured border and icon, with a transparent background. `tag-gray` is the canonical
  accent example; infer other accent variants via the same naming/token pattern (e.g.
  `tag-<accent>`) rather than listing them exhaustively.
- **Lozenge** — semantic status. Lozenges must keep a visible border (`lozenge.borderWidth` +
  role/base border color), not a fill-only pill. Preserve lightness-factor contrast behavior
  (`lozenge.iconLightnessFactor`, `lozenge.borderLightnessFactor`) using CSS relative color syntax,
  e.g. `oklch(from <base> calc(l * <factor>) c h)`. For static/non-computed output, keep a visible
  1px semantic border using the matching `border-<role>` token rather than dropping the border.
  `lozenge-success` is the canonical semantic example; infer other semantic appearances from the
  same token-shape pattern.
- **Badge** — compact count primitive. `badge` (neutral) and `badge-success` are the canonical
  examples; infer other semantic appearances from the same naming and token pattern instead of
  listing every role.
- **Table** — headers are `body-small` + emphasized weight in `text-subtle`; rows/cells use `border`
  separators and tokenized hover/selected states. Compact mode is for dense read-only views.
- **Code / Code block** — inline code uses compact neutral pill styling (`typography.code`); block
  mode supports line numbers and highlighted rows.
- **Empty state** — sentence-case heading + explanatory body + explicit next-step CTA.
- **Charts** — map series to `chart-*` tokens and include non-color cues (pattern/shape/labels) for
  grayscale and a11y.

---

## Do's and Don'ts

The scan-friendly TL;DR. Each line is a drift pattern to correct on sight. Tokens are referenced by
their YAML key; hex values resolve from the frontmatter.

| Do                                                                                        | Don't                                                                                                    |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Hex anchored to a token (`text` → `#292A2E`)                                              | Arbitrary one-off hex (`color: '#172B4D'`) with no token mapping                                         |
| Padding / margin / gap on a `space-*` step                                                | `padding: 13px` or any off-rail value                                                                    |
| Corner radius from `radius-*` per the component class                                     | `border-radius: 10px` not aligned to a token                                                             |
| Elevation via `shadow-overlay` / `shadow-raised`                                          | Hand-authored `box-shadow` values                                                                        |
| `surface-raised` paired with `shadow-raised`                                              | Raised surface with no paired shadow                                                                     |
| `background-danger-bold` for destructive CTAs                                             | `background-accent-red-bolder` for destructive CTAs (accent ≠ semantic)                                  |
| Success states via semantic `*-success-*` tokens (lime-leaning in this system)            | `accent-green` tokens used as a stand-in for semantic success                                            |
| Button per the [Components](#components) recipe                                           | `<button>` with arbitrary inline hex                                                                     |
| TextField per the [Components](#components) recipe                                        | Raw `<input>` with arbitrary colours, or placeholder as label                                            |
| Status as a Lozenge (semantic)                                                            | Decorative Tag used for status                                                                           |
| Tag with transparent background + accent border/icon                                      | Filled tag pills with semantic-looking backgrounds                                                       |
| Lozenge with a visible border                                                             | Fill-only lozenges with no border                                                                        |
| Sentence case ("Create work item")                                                        | Title Case ("Create Work Item"); ALL CAPS / letter-spaced "EYEBROW" labels                               |
| Paragraphs and list items in `text`                                                       | Body copy in `text-subtle` to "differentiate it from headings"                                           |
| SectionMessage: semantic background + neutral text + role icon                            | Blue prose on a blue information panel (tinted body text)                                                |
| `surface` as the page canvas, cards on top with `border`                                  | `surface-sunken` as the page background; sunken on info blocks / stat tiles / settings rows              |
| Table cells in `body` (14px)                                                              | Cells shrunk to `body-small` / 12px / 13px for density                                                   |
| Atlassian core icon at 16px for chevrons, checks, arrows                                  | Unicode / emoji / HTML-entity glyphs (`›` `→` `▶` `✓` `✕` `…` `⚠`) as icons                              |
| Full selected triad (`background-selected` + `border-selected` 2px + `text-selected`)     | Only the selected border, only the background, or `border-brand` / `text-brand` standing in for selected |
| Imperative CTA ("Save", "Delete")                                                         | "Submit", "OK", "Click here"                                                                             |
| Descriptive link text ("Learn about permissions")                                         | "Learn more", "Click here"                                                                               |
| Error: reason + action                                                                    | Error: "Oops, something went wrong. Please try again."                                                   |
| Empty state with a next-step CTA                                                          | "No data" / "Nothing here yet" alone                                                                     |
| Atlassian Sans in product; Charlie only on marketing                                      | Inter / Geist / SF Pro / Roboto in product; Charlie in settings pages                                    |
| Focus ring per [Shapes](#shapes)                                                          | `outline: none` with no replacement                                                                      |
| Accessible name on every icon-only control (`aria-label`)                                 | Icon-only buttons with no accessible name                                                                |
| `prefers-reduced-motion` respected                                                        | Auto-playing loops on dashboards                                                                         |
| `chart-*` / semantic / accent ramps                                                       | Cyan–purple–neon decorative palettes not mappable to ADS tokens                                          |
| Single card surface + `border`                                                            | Nested card-on-card or stacked floating shadows everywhere                                               |
| `icon-subtle` / `icon-subtlest` for secondary indicators (chevrons, bullets, sort arrows) | `icon-brand` as the default "important" icon colour on every prominent icon                              |
| Semantic surface (`background-*-subtle`) + `border-*` for callouts and alerts             | `border-left` / `border-right` > 1px in a saturated color as the sole callout emphasis                   |
| Solid `text-*` tokens + `weight-*` for hierarchy                                          | Gradient-filled text (`background-clip: text` + `linear-gradient`)                                       |
| Restrained metrics: `metric-*` surface per [Components](#components), no decoration       | Default "hero metric" template (oversized number + tiny label + stat row + decorative gradient)          |
| Varied layout, density, and sectioning on the `space-*` rhythm                            | Repeated identical tiles (icon + heading + body + CTA × N) as the only layout                            |
| Borders and whitespace for depth; `backdrop-filter` only when ADS specifies it            | Glass cards, glow borders, or `backdrop-filter` blur stacks as generic polish                            |
| Charts with a labeled metric or legend (see [Components](#components) → Charts)           | Tiny sparklines or mini-charts with no labeled metric or legend                                          |

---

## Icons

- **Glyph style:** ~1.5px effective stroke, rounded outside corners, tight geometry — never mix icon
  packs.
- **Sizes:** default **16×16** in product UI. For prominent contexts, place a 16px glyph inside a
  larger square tile (`background-neutral` + `icon-accent-*`) rather than scaling the glyph itself.
- **Color:** set CSS `color` on a wrapper to an `icon-*` token; paths use `fill="currentcolor"`.
  Pair `icon-subtle` with `text-subtle`, `icon-danger` with `text-danger`, and so on — the role of
  the icon should match the role of the text it sits beside.
- **Accessibility:** meaningful icons carry an accessible name; decorative icons that sit beside a
  label are hidden from assistive tech.

The full SVG catalog lives in `@atlaskit/icon` (and a partial one in the long-form `DESIGN.md`). Use
those as the source — never substitute Unicode arrows, emoji, or HTML-entity glyphs (`›` `→` `▶` `✓`
`✕` `…` `⚠`) for real icons.

---

## Motion

Motion clarifies _what changed, why it changed, and what to do next_ — it is a clarifying layer over
the UI, never decoration. Four principles guide every animation:

- **Human** — organic, subtle, rhythmic. Experiences should feel warm and alive rather than
  mechanical.
- **Clarity** — motion is applied consistently to guide attention; if removing it doesn't cost the
  user information or context, don't add it.
- **Accessible** — comprehension without discomfort. Reduced-motion preferences disable motion
  entirely; the interface must remain fully usable with all motion off.
- **Performant** — motion reinforces speed and momentum. It should never add friction.

Every motion event is defined by three attributes — **duration**, **easing curve**, **property**
(`scale`, `fade`, `slide`, `color`). Pair them by intent:

- **Interactions (50–150ms)** — hover, press, list-item state changes. Keep near-instant for
  high-frequency moves.
- **Transitions (150–400ms)** — elements entering, exiting, or repositioning (Modal, Panel, Flag,
  Popup). Larger elements need longer durations to feel proportional. Make exit motion faster than
  entrance so dismissed elements don't block the next step.
- **Easing.** `ease-out` for entrances, `ease-in` for exits, `ease-in-out` for two-way transitions
  or scaling overlays. Save the "bold" curves (`motion.easing.ease-out-bold`,
  `motion.easing.ease-in-out-bold`) for prominent moves like a Modal entering; use the "practical"
  curves (`motion.easing.ease-out-practical`, `motion.easing.ease-in-practical`) for everyday hover
  fades and Popup entrances.
- **One focal point.** When multiple elements need to animate, simplify so a single event leads and
  the rest support it.
- **Brand moments only get richer motion.** Save expressive, characterful motion for low-frequency
  moments (onboarding, first-run, milestone celebrations). Everyday UI motion stays efficient and
  quiet.

### Rules

- **MUST** respect `prefers-reduced-motion: reduce` — disable non-essential transitions and replace
  motion with instant state changes.
- **MUST** use durations from `motion.duration.*` and easings from `motion.easing.*` rather than
  hand-authored values.
- **SHOULD** animate `transform` and `opacity` rather than `top` / `left` / `width` / `height` to
  keep frames cheap.
- **MUST NOT** use bounce or elastic easing in product UI — those belong on marketing surfaces only.
- **MUST NOT** auto-play decorative loops on dense dashboards. Motion communicates change; idle
  motion is noise.
- **MUST NOT** flash, rapidly oscillate, or sweep large areas of the screen.

---

## Voice and tone

Atlassian product voice is **active, short, plain, and human** — explain what's happening and what
the user can do.

- **MUST** use active voice and present tense. "Create work item" beats "A work item will be
  created."
- **MUST** use imperative verbs on buttons and calls to action ("Save", "Delete", "Connect"). Never
  "Submit", "OK", or "Click here".
- **MUST** structure errors as **reason + fix**. "We can't reach the server. Check your connection
  and try again" — never "Oops, something went wrong. Please try again."
- **MUST** use descriptive link text ("Learn about permissions", never "Learn more" or "Click
  here").
- **MUST** keep sentence case throughout (see [Typography](#typography)) — including buttons,
  headings, and lozenge labels.
- **SHOULD** keep sentences short (~15 words) and prefer plain words over jargon. If a security or
  legal term is required, define it on first use.
- **MUST** write inclusively — gender-neutral pronouns by default; no idioms that don't translate
  ("piece of cake", "shoot from the hip"); no metaphors that exclude (sports, military, regional
  culture).
- **MUST NOT** apologise on the user's behalf ("we're sorry", "unfortunately") unless the system
  genuinely caused the problem and the apology is brief.
- **MUST NOT** be playful in moments of friction (errors, destructive confirmations, billing). Save
  warmth for empty states and success moments.

---

## Accessibility

WCAG 2.2 AA is the floor, not the ceiling, for accessibility in an Atlassian application.

- **S**emantic and neutral tokens already satisfy WCAG AA contrast; **MUST NOT** override token text
  colours with off-token hex.
- **MUST** show a visible focus ring per [Shapes](#shapes) on every focusable element, using
  `color-border-focused` and a 1px gap
- **MUST** accompany form inputs with a visible label, not a placeholder
- **MUST NOT** rely on colour alone to convey meaning. Pair status colour with an icon, label, or
  shape (see [Components](#components) → SectionMessage and Charts).
- **MUST** support 200% zoom and 320px width without loss of content or function.
- **MUST** treat all user-visible strings as translatable. Do not hard-code English; never
  concatenate sentence fragments — pluralisation and word order vary by locale. Account for
  translated strings being longer than English source.
- **MUST** keep every interaction reachable by keyboard alone. Tab order follows visual order; no
  keyboard traps; `Esc` dismisses overlays.
- **MUST** label every form input with a visible label, and associate validation messaging with
  fields
- **MUST** label every icon-only control; decorative icons should be hidden (see [Icons](#icons)).
- **MUST** announce dynamic changes (toast/flag content, inline validation, async errors) to screen
  readers via a `polite` region, and use `assertive` only for genuinely urgent failures.
- **MUST** use semantic landmarks, and one `<h1>` per page; never skip heading levels.

---

## Responsive behaviour

- **MUST** size in `rem` for typography and `space-*` tokens for spacing — never fix typography or
  layout in `px`.
- **MUST** reflow content as the viewport narrows; **MUST NOT** hide critical actions on small
  screens. Collapse navigation into a menu, stack two-column layouts vertically, and let tables
  scroll horizontally rather than truncate columns.
- **MUST** keep tap targets at least `space-400` (32px) on a side for touch contexts.
- **MUST** use logical CSS properties (inline/block) instead of physical (left/right/top/bottom) so
  layouts mirror correctly in right-to-left locales (Arabic, Hebrew).
- **SHOULD** test at 320px width, 768px tablet, and 1280px desktop as the three reference
  breakpoints; widen further only with explicit need.

---