Atlassian Design System

---
name: atlassian-design-system
description: Apply the Atlassian Design System visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Atlassian Design System, mentions ADS, Atlaskit, Atlassian Design System, or describes brand blue #1868db, dark navy text #172b4d, sunken gray wells — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Atlassian Design System Design System

The system behind Jira, Confluence, and Trello: collaboration-neutral light UI with brand blue #1868db (evolved from the long-lived #0052cc), dark-navy #172b4d text, sunken #f7f8f9 wells, 8px-base spacing tokens, small 4–12px radii, and a fully tokenized elevation and color model that renders its palette live from design tokens.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values come from the officially published token set. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Atlassian Design System.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (ADS, Atlaskit, Atlassian Design System, Jira style), or describes its traits: brand blue #1868db; dark navy text #172b4d; sunken gray wells; token-driven theming (color.*, space.*); cards and boards; left navigation + top bar.

## Design tokens

### Color palette

- elevation.surface — default page surface: `#ffffff` (--color-bg)
- elevation.surface.sunken — board columns, wells, page background zones: `#f7f8f9` (--color-surface-sunken)
- color.text — dark navy primary text: `#172b4d` (--color-text)
- color.text.subtle — secondary text (legacy N200): `#6b778c` (--color-text-muted)
- Brand blue for actions and links (legacy B400 #0052cc): `#1868db` (--color-accent)
- color.border — dividers and control outlines: `#dfe1e6` (--color-border)
- color.text.danger / destructive actions: `#de350b` (--color-danger)
- color.icon.success — confirmation states: `#22a06b` (--color-success)

### Dark mode overrides

When building dark mode, override these roles (all other tokens stay the same):

- elevation.surface in dark theme: `#1d2125` (--color-bg)
- color.text in dark theme: `#b6c2cf` (--color-text)
- Brand blue adjusted for dark theme: `#579dff` (--color-accent)

### Typography

- Display / headings: Inter (fallback: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif) (ideal: Atlassian Sans, premium — use Inter as the free substitute)
- Body: Inter (fallback: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif) (ideal: Atlassian Sans, premium — use Inter as the free substitute)
- Mono / data: IBM Plex Mono (fallback: SFMono-Regular, Consolas, monospace) (ideal: Atlassian Mono, premium — use IBM Plex Mono as the free substitute)
- Type scale: 1.2 ratio, base 14px — computed steps: 14px / 17px / 20px / 24px / 29px / 35px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 600, line-height 1.25, letter-spacing -0.01em
- Body: line-height 1.43, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 2, 4, 8, 12, 16, 24, 32, 40 — 8px-base token scale (space.100 = 8px, with 2/4px fine steps): 16px card padding, 8px gaps between cards on boards, 24px page margins — collaborative-tool density between consumer and data-grid extremes.
- Border radius: sm 4px, md 8px, lg 12px, full 9999px — Controls and inputs use ~4px (border.radius), cards 8px, modals and larger containers 12px; avatars and lozenge-adjacent shapes go full round.
- Border treatment: 1px solid #dfe1e6 — 1px color.border hairlines; inputs use a 2px border that turns brand blue on focus, one of ADS's more distinctive control treatments.

### Shadows

- raised: `0 1px 1px rgba(9, 30, 66, 0.25), 0 0 1px rgba(9, 30, 66, 0.31)` — elevation.shadow.raised — cards on boards
- overlay: `0 8px 12px rgba(9, 30, 66, 0.15), 0 0 1px rgba(9, 30, 66, 0.31)` — elevation.shadow.overlay — modals, dropdown menus, flags

### Layout

- Max content width: 1440px
- App frame: slim top bar plus collapsible left sidebar navigation with project/space switcher
- Boards: horizontally scrolling sunken columns of raised cards
- Content pages (Confluence-style) cap the text column near 760px for readability
- Inline edit everywhere — click text to edit in place rather than separate edit screens

### Effects

- Lozenges: small uppercase 3px-radius status chips in tinted fills (blue in-progress, green done, red blocked)
- Notification 'flags' slide in bottom-left with the overlay elevation

### Motion

- Easing: cubic-bezier(0.15, 1, 0.3, 1); durations 100ms / 175ms / 350ms
- Entering elements decelerate (ease-out); exits are faster than entrances
- Card drag-and-drop lifts with a slight tilt and stronger shadow
- Small fades and 4px slides for menus; nothing bounces in productivity surfaces

## CSS variables (drop-in)

```css
:root {
  --color-bg: #ffffff;
  --color-surface-sunken: #f7f8f9;
  --color-text: #172b4d;
  --color-text-muted: #6b778c;
  --color-accent: #1868db;
  --color-border: #dfe1e6;
  --color-danger: #de350b;
  --color-success: #22a06b;
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;
  --shadow-raised: 0 1px 1px rgba(9, 30, 66, 0.25), 0 0 1px rgba(9, 30, 66, 0.31);
  --shadow-overlay: 0 8px 12px rgba(9, 30, 66, 0.15), 0 0 1px rgba(9, 30, 66, 0.31);
  --border-default: 1px solid #dfe1e6;
  --font-display: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  --font-body: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  --font-mono: "IBM Plex Mono", SFMono-Regular, Consolas, monospace;
  --text-base: 14px;
  --leading-heading: 1.25;
  --leading-body: 1.43;
  --tracking-heading: -0.01em;
  --tracking-body: 0;
  --ease: cubic-bezier(0.15, 1, 0.3, 1);
  --duration-fast: 100ms;
  --duration-base: 175ms;
  --duration-slow: 350ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** Top bar (48px, white, 1px bottom border) with product switcher, search, and avatar; left sidebar 240px on surface color with 36px rows and blue-tinted selected states
- **Hero:** Product pages open with a breadcrumb, a 24px/600 navy title, and action buttons right-aligned; marketing surfaces use big navy headlines with blue CTAs on white
- **Card:** White surface, 8px radius, raised shadow, 16px padding; board cards add labels, lozenges, and avatar stacks at 8px gaps
- **Button (primary):** Brand blue #1868db fill, white 500-weight text, 4px radius, 32px tall; hover darkens toward legacy #0052cc territory, pressed darker still
- **Button (secondary):** Transparent or #f7f8f9 'subtle' fill, navy text, no border until hover adds a neutral tint; ADS favors subtle buttons over outlined ones
- **Form fields:** 12px/600 label above; 40px input with 2px #dfe1e6 border, 3px radius; focus swaps the full 2px border to brand blue — no glow, just the color change

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The board-and-card idiom: white 8px-radius cards with the raised elevation token floating in sunken #f7f8f9 columns, under a navy-inked interface where the only strong color is Atlassian blue on actions and links. Spend boldness here; keep everything else quiet.

## Do

- Consume color.* and space.* tokens rather than raw values — Atlassian re-renders its palette live and tokens track it
- Keep text navy #172b4d, not black; it is the most recognizable ADS trait
- Use lozenges for every status; colored free text is not the ADS way
- Prefer 'subtle' secondary buttons (tint on hover) over outlined buttons

## Don't

- Don't mix the legacy #0052cc and current #1868db brand blues in one interface — pick the current token and let hover states darken
- Don't put heavy shadows on resting content; only raised cards and overlays elevate
- Don't use uppercase headings — ADS is sentence case except inside lozenges
- Don't crowd boards: cards keep 8px gaps and columns keep their sunken background

## Accessibility notes

- Navy #172b4d on white is about 13.9:1; subtle text #6b778c on white sits right at the 4.5:1 AA line — do not use it below 14px or on tinted surfaces without rechecking
- Brand blue #1868db on white passes AA (~5:1) for text and meets 3:1 for UI components
- Lozenge tint pairs come from contrast-checked token pairs — use the published bold/subtle lozenge combinations rather than inventing tints

## Reference sites

- Atlassian Design System: https://atlassian.design
- ADS color foundations: https://atlassian.design/foundations/color-new
- ADS components: https://atlassian.design/components

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip atlassian-design-system.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/atlassian-design-system.json

Settings → Capabilities → Skills → Upload skill → atlassian-design-system.zip