atlassian-design-system

Atlassian Design System — design system operations

Research snapshot: 2026-07-30. This file records only public operating information; several contribution and governance details are intentionally restricted to Atlassian employees.

1. Governance

• Atlassian Design System is built and supported by Atlassian developers, designers, and content designers and is used by internal teams, Marketplace partners, and external users. About Atlassian Design System
• The public site identifies a Design System team as the support and coordination point. The team’s principles include solving system needs before individual features, treating documentation/support/tooling/maintenance as part of shipping, incorporating multiple perspectives, and bringing product teams into co-creation. About Atlassian Design System
• Contributions are currently accepted only from Atlassian employees. External users can provide page feedback and use the public developer community, but cannot use the internal contribution path. Contribution
• The public contribution page says the team currently accepts fixes and small, non-breaking enhancements. It may be unable to accept major component changes, system-wide behavior changes, new components, or new patterns; teams with such needs are directed to contact the Design System team. Contribution
• Internal governance mechanisms include Slack support, fortnightly Design System critique sessions, and internal-only contribution and release-phase guidance. Contribution, Release phases

2. Component lifecycle

• Atlassian publishes three release phases: Early Access, Beta, and General Availability. Early Access is experimental, can contain breaking changes in 0.x minor releases, and is intended for pilot groups; Beta is supported and stable at 1.0+, with infrequent breaking changes confined to major releases; General Availability is fully stable and ready to use. Release phases
• It also publishes two deprecation phases: Intent to Deprecate (Caution), which warns against new adoption and points to an alternative, and Deprecated, which is unsupported and scheduled for removal after a communicated deprecation period. A GA feature will not be removed without an announced deprecation period. Release phases
• Component and foundation directories display phase badges such as Early access, Beta, Caution, and Deprecated. Stable/GA entries commonly appear without a badge in the directory. Components
• Public documentation defines what each phase means to consumers, but the criteria and approval mechanics for moving between phases are in employee-only guidance rather than the public page. Release phases
• Release announcements show feedback and testing between Beta and GA and publish a migration/support window when older systems are deprecated. Typography GA announcement

3. Contribution process

• Internal contributors can ask questions in Slack, attend fortnightly system critique, report bugs, and propose small enhancements. The currently supported contribution scope is fixes and small changes that do not break behavior and can be contained. Contribution
• Major enhancements and new components/patterns require system-wide coordination and may not be accepted through the current contribution path. Teams are instructed to contact the Design System team so the case can be understood. Contribution
• Icon contribution is more specifically documented: contributors first check for duplication, ambiguity, and whether an icon is needed, then use an employee-only contribution guide. Atlassian’s icon contribution tooling automates source-card creation, metadata, export, organization, preview, and publish status. Iconography, Icon system case study
• Code consumers are directed to install the design-system ESLint plugin, which provides in-editor accessibility pointers, deprecation notices, and other system guidance. Develop for Atlassians
• Public documentation does not expose the internal pull-request approval matrix, code-owner rules, or formal proposal template for general component work.

4. Versioning and release cadence

• Components are distributed as independently versioned @atlaskit/* npm packages. The release-phase contract states that Early Access 0.x packages can break in minor releases, while Beta 1.0+ packages confine breaking changes to major versions; GA is fully stable. Release phases
• Individual component pages include changelog routes, and npm records package versions and publish dates. Different packages release independently and can publish multiple versions in a short period. Button group changelog, @atlaskit/button on npm
• Broader design-language changes are communicated through the public “What’s new” channel, including feature deep dives, release roundups, GA announcements, deprecation dates, migration guidance, codemods, and support windows. What’s new, Typography GA announcement
• The public operations documentation does not state one fixed release cadence for all ADS packages. Public package histories show independently shipped, frequent releases rather than a synchronized system release train. @atlaskit/button on npm

5. Documentation structure and templates

• The component site organizes content by component and exposes separate routes for Usage, Examples, Code, and Changelog where applicable. Pages begin with the component’s purpose and display release-phase or deprecation warnings in context. Button usage, Button examples, Button code, Button group changelog
• Code documentation includes per-package installation instructions; the developer setup guide points users to each component’s code documentation after installing the shared tooling. Develop for Atlassians
• Component-specific guidance can include detailed accessibility patterns and examples, such as equivalent controls, accessible naming, live-region feedback, keyboard behavior, and focus restoration for drag and drop. Drag-and-drop accessibility guidelines
• Site pages include a feedback collector, providing a direct documentation feedback mechanism for both internal and external users. Contribution
• Public sources show a consistent information architecture but do not publish a general component-page authoring template.

6. Naming and token conventions

• Atlassian describes design tokens as the single source of truth for named design decisions. Token names are semantic and dot-separated in code, for example color.background.neutral, space.200, and font.body; generated CSS custom properties use the --ds- prefix. Design tokens explained, Use tokens in code
• Token names are read as foundation → property → modifier. The foundation identifies a design domain such as color or space; the property identifies the UI target such as text, icon, border, or background; modifiers encode role, emphasis, or interaction state. Design tokens explained
• Consumers are instructed to choose tokens by meaning, not by matching a current raw value, because values change across themes. Design tokens explained
• The token() API adds the correct namespace, type checking, and warnings for unknown tokens. ESLint and Stylelint rules enforce token use, warn on deprecated tokens, and prevent unsafe token use. Use tokens in code
• Components are published under the @atlaskit package scope and use descriptive names aligned with component purpose. Develop for Atlassians

7. Accessibility criteria and enforcement

• Accessibility is a stated design-system value and quality standard. The public principles call for research and clear standards for accessibility, responsiveness, and enterprise scale. About Atlassian Design System
• Accessibility is enforced partly through component APIs that make semantic choices explicit, as in separate link and button primitives, and through migration tooling. Atlassian describes new button/link APIs as preventing common accessibility errors by construction. Evolving buttons and links
• The recommended design-system ESLint plugin provides in-editor accessibility pointers and rules for accessible names, semantic HTML replacements, headings, focus behavior, and prohibited or deprecated APIs. Develop for Atlassians, ESLint plugin
• Component guidance includes accessibility details for complex interactions. For drag and drop, Atlassian requires equivalent non-drag controls, meaningful assistive names, live-region announcements, and focus restoration. Drag-and-drop accessibility guidelines
• Phase promotions can reflect accessibility testing and user feedback; the typography GA announcement documents legibility testing, feedback-driven refinements, and changes that correct heading-semantics problems. Typography GA announcement
• The public site does not expose a universal pass/fail accessibility checklist or test matrix for every component.

8. Audit and review cycle

• Atlassian describes continuous feedback as a principle and provides fortnightly system critique sessions for internal teams. About Atlassian Design System, Contribution
• Tooling detects drift at authoring time: ESLint and Stylelint warn about deprecated tokens and APIs, enforce token usage, and steer code toward current components and primitives. Use tokens in code, ESLint plugin
• Release and deprecation phases make status visible in the component directory and require a communicated replacement and deprecation period before GA removal. Components, Release phases
• Large migrations can include codebase usage review, direct team outreach, new lint rules, and codemods; the button/link migration covered approximately 2,000 call sites. Evolving buttons and links
• Public documentation does not specify a fixed periodic inventory audit. The observable model combines ongoing feedback, critique, lint-based drift detection, phase badges, usage reviews during redesigns, codemods, and announced deprecation windows.