DESIGN.md — Atlassian Design System (Atlaskit)

Design System

Name: Atlassian Design System (Atlaskit) Maintainer: Atlassian Version: v1 / current (packages versioned independently under @atlaskit/) Target platforms: Web (React primary) Audience: Teams building Atlassian product UI (Jira, Confluence, Trello, Bitbucket, etc.)

Color

Color model: Semantic token system (color.*) over a raw palette. Tokens encode property + role + emphasis + state. Themes: Light (default) and Dark — tokens resolve to different palette values per theme Primary brand color: Blue 700 (#1868DB) — used for primary actions, selected states, links

Token naming

color.<property>.<role>.<emphasis>.<state>

Examples:
  color.background.brand.bold          → #1868DB (primary button background)
  color.background.brand.bold.hovered  → #1558BC
  color.text                           → #292A2E (default text)
  color.text.subtle                    → #505258
  color.text.subtlest                  → #6B6E76
  color.text.disabled                  → rgba(8, 15, 33, 0.29)
  color.text.inverse                   → #FFFFFF (text on bold backgrounds)
  color.text.danger                    → #AE2E24
  color.text.warning                   → #9E4C00
  color.text.success                   → #4C6B1F
  color.text.discovery                 → #803FA5
  color.text.information               → #1558BC
  color.icon.brand                     → #1868DB
  color.border.focused                 → #4688EC
  color.border.input                   → #8C8F97
  elevation.surface                    → #FFFFFF
  elevation.surface.sunken             → #F8F8F8 (recessed surfaces)
  elevation.surface.overlay            → #FFFFFF (modals, popovers)

Color roles

Role	Used for
`neutral`	Default UI, secondary buttons, nav elements
`brand`	Primary actions, Atlassian brand identity
`information`	In-progress, informational states
`success`	Favorable outcomes
`warning`	Caution, potential errors
`danger`	Errors, destructive actions
`discovery`	New features, onboarding
`accent`	Semantic-free color labels (lime, red, green, blue, yellow, orange, teal, purple, magenta, gray)
`inverse`	Content on bold-emphasis backgrounds
`input`	Form field fills

Emphasis levels

Backgrounds have 4 emphasis tiers: subtlest → subtler → subtle → bold (highest contrast)

Interaction states

States encoded in token name: .hovered, .pressed. Disabled uses alpha values rather than tint.

Accessibility

WCAG AA target: 4.5:1 for small text, 3:1 for large text and UI components.

Typography

Typeface: Atlassian Sans (product UI), Atlassian Mono (code)

Body/Heading: "Atlassian Sans", ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Ubuntu, system-ui, sans-serif
Code: "Atlassian Mono", ui-monospace, Menlo, 'Segoe UI Mono', Ubuntu Mono, monospace
Brand (marketing only): Charlie Display / Charlie Text

Unit system: rem (base 16px)

Type scale

Token	Size	Line-height	Weight
`font.heading.xxlarge`	2rem / 32px	2.25rem	653
`font.heading.xlarge`	1.75rem / 28px	2rem	653
`font.heading.large`	1.5rem / 24px	1.75rem	653
`font.heading.medium`	1.25rem / 20px	1.5rem	653
`font.heading.small`	1rem / 16px	1.25rem	653
`font.heading.xsmall`	0.875rem / 14px	1.25rem	653
`font.heading.xxsmall`	0.75rem / 12px	1rem	653
`font.body.large`	1rem / 16px	1.5rem	400
`font.body`	0.875rem / 14px	1.25rem	400
`font.body.small`	0.75rem / 12px	1rem	400
`font.code`	0.875em	1	400

Note: Weight 653 is Atlassian's custom bold tuned for Atlassian Sans.

Spacing

Scale: space.* tokens, rem-based

space.0:    0rem      (0px)
space.025:  0.125rem  (2px)
space.050:  0.25rem   (4px)
space.075:  0.375rem  (6px)
space.100:  0.5rem    (8px)
space.150:  0.75rem   (12px)
space.200:  1rem      (16px)
space.250:  1.25rem   (20px)
space.300:  1.5rem    (24px)
space.400:  2rem      (32px)
space.500:  2.5rem    (40px)
space.600:  3rem      (48px)
space.800:  4rem      (64px)
space.1000: 5rem      (80px)

Negative spacing: space.negative.025 through space.negative.400.

Shape (Border Radius)

Scale: radius.* tokens

radius.xsmall:  0.125rem / 2px
radius.small:   0.25rem  / 4px
radius.medium:  0.375rem / 6px
radius.large:   0.5rem   / 8px
radius.xlarge:  0.75rem  / 12px
radius.xxlarge: 1rem     / 16px
radius.full:    624.9375rem (pill)
radius.tile:    25% (avatar tiles)

Elevation

Elevation is expressed through surface background tokens and shadow tokens (not opacity-based):

elevation.surface:           #FFFFFF  (default page)
elevation.surface.sunken:    #F8F8F8  (recessed areas)
elevation.surface.raised:    #FFFFFF  (cards, with shadow)
elevation.surface.overlay:   #FFFFFF  (modals, dropdowns, with shadow)

elevation.shadow.raised:   0px 1px 1px rgba(30,31,33,0.25), 0px 0px 1px rgba(30,31,33,0.31)
elevation.shadow.overlay:  0px 8px 12px rgba(30,31,33,0.15), 0px 0px 1px rgba(30,31,33,0.31)

Token Architecture

Single tier: All-semantic, no explicit primitive tier exposed to consumers.

Tokens reference internal palette primitives that are not meant for direct use. Consumer-facing tokens are all role-based and follow the dot-path naming convention.

Token package: @atlaskit/tokens CSS custom property prefix: --ds-* JavaScript API: token('color.background.brand.bold')

Installation

yarn add @atlaskit/tokens
yarn add @atlaskit/primitives
yarn add @atlaskit/button @atlaskit/heading  # per component

import { setGlobalTheme } from '@atlaskit/tokens';
setGlobalTheme({ colorMode: 'light' });  // or 'dark', 'auto'

import { Box, Stack } from '@atlaskit/primitives';
import { token } from '@atlaskit/tokens';

function MyComponent() {
  return (
    <Box
      backgroundColor="elevation.surface.raised"
      padding="space.300"
    >
      content
    </Box>
  );
}

Build target: React 16.8+, Node.js 18+, Webpack/Vite/etc.