--- system: atlassian category: design-md topic: DESIGN.md content_type: design-md status: latest version_label: "v1 (current)" retrieved: 2026-05-12 unofficial: true design_md_spec_version: alpha derived_from: - guidance/foundations/color@2026-05-12.md - guidance/foundations/typography@2026-05-12.md - guidance/foundations/design-tokens@2026-05-12.md - implementation/getting-started@2026-05-12.md - assets/tokens/colors@2026-05-12.json source_url: https://atlassian.design tags: [design-md, atlassian, atlaskit, enterprise] --- # 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.... 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 ```bash yarn add @atlaskit/tokens yarn add @atlaskit/primitives yarn add @atlaskit/button @atlaskit/heading # per component ``` ```tsx import { setGlobalTheme } from '@atlaskit/tokens'; setGlobalTheme({ colorMode: 'light' }); // or 'dark', 'auto' ``` ```tsx import { Box, Stack } from '@atlaskit/primitives'; import { token } from '@atlaskit/tokens'; function MyComponent() { return ( content ); } ``` **Build target:** React 16.8+, Node.js 18+, Webpack/Vite/etc.