Welcome to the Atlas Design project! This repository holds the source code backing the Atlas Design System.

The Atlas Design System strives to empower designers, PMs, and developers to build accessible, high quality, and consistent experiences at scale across the Microsoft Skilling web properties. Atlas powers Microsoft Learn 🤓!

Looking for information about the Atlas CSS framework? Start in /css!

• We care deeply about accessibility. Microsoft Learn is one of the very few large Grade B websites.
• We are a low-level design system that focuses on CSS and only uses zero-dependency JS when required for good interactions or accessibility.
• We are compatible with right-to-left reading direction thanks to our use of logical properties.
• We are themeable, with three themes right out of the box (Light, Dark, and High Contrast), and we support an unlimited number of themes.
• We provide example markup. Our website is spartan compared to many design system websites. Its main purpose is for atomic/component documentation and to provide accessible code snippets.
• We have atomics for flexibility and components for consistency.
• We have a VSCode extension that provides helpful IntelliSense and class completion in the IDE.
• We publish to NPM.

Name	Status
@microsoft/atlas-css
@microsoft/atlas-js
Release Pipeline
PR Builds

• Ensure git is installed.
• Ensure that have downloaded and installed a version of NodeJS that supports monorepos. It's currently recommended you download NodeJS version 18.12.1 and use with NPM at a greater version than 8.19.2.
• Alternatively, you can install NPM with NVM: mac | windows.
• If contributing code, please read about using changesets and semantic versioning bump types.
• Clone the repostory.
• From the root directory, run npm install.

The styles backing the Atlas Design system are discussed in greater detail in /css.

Use NPM to add @microsoft/atlas-css to your project.

# install with NPM
npm install --save @microsoft/atlas-css

You may access any file within the /css folder using the following UNPKG url. Just add the path to the file, relative to the @ sign or version the end.

https://unpkg.com/browse/@microsoft/atlas-css/ # Will redirect to latest version
https://unpkg.com/browse/@microsoft/atlas-css@<version>/ # Use this pattern on your page

Behaviors and elements beyond the scope of CSS are found in the /js folder.

# install with NPM
npm install --save @microsoft/atlas-js

While this project is open source, its primary purpose is to serve Microsoft web properties through a CSS-first implementation of a design system. We do appreciate contributions to our documentation (/site folder), our framework (/css), and its companion scripts (/js).

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

The following commands can be used to update broadly update dependencies. (Note: we omit major updates to husky because of major api changes and a general preference for version 4.x)

npm exec --package npm-check-updates --workspaces --include-workspace-root -- npm-check-updates --upgrade --reject husky
npm exec --package npm-check-updates --workspaces --include-workspace-root -- npm-check-updates --upgrade --target minor
rm package-lock.json
npm i