diff --git a/modules/primer-avatars/README.md b/modules/primer-avatars/README.md
index c2e1d98c8b..c2a7436dc2 100644
--- a/modules/primer-avatars/README.md
+++ b/modules/primer-avatars/README.md
@@ -75,14 +75,62 @@ When you need a larger parent avatar, and a smaller child one, overlaid slightly
### Avatar stack
-Stacked avatars can be used to show who is participating in thread when there is limited space available. When you hover over the stack, the avatars will reveal themselves. Optimally, you should put no more than 3 avatars in the stack.
+Stacked avatars can be used to show multiple collaborators or participants when there is limited space available. When you hover over the stack, the avatars will reveal themselves.
```html
-
- 
- 
- 
-
+
+```
+
+Based on the number of avatars in the stack, add these modifier classes:
+- `AvatarStack--two` for 2 avatars.
+- `AvatarStack--three-plus` for 3 or more avatars.
+
+If you have more than three avatars, add a div with the classes `avatar avatar-more` as the third avatar in the stack, as such:
+
+```html
+
+```
+
+You can also link individual avatars. To do this shift the `avatar` class over to the anchor:
+
+```html
+
+```
+
+Use `AvatarStack--right` to right-align the avatar stack. Remember to switch the alignment of tooltips when making this change.
+
+```html
+
```
## Circle Badge
diff --git a/modules/primer-avatars/lib/avatar-stack.scss b/modules/primer-avatars/lib/avatar-stack.scss
index 884f6a528d..4457a361a0 100644
--- a/modules/primer-avatars/lib/avatar-stack.scss
+++ b/modules/primer-avatars/lib/avatar-stack.scss
@@ -43,3 +43,137 @@
}
}
}
+
+// Refactored, new avatar stack:
+
+.AvatarStack {
+ position: relative;
+ min-width: 26px;
+ height: 20px;
+
+ .AvatarStack-body {
+ position: absolute;
+ }
+
+ &.AvatarStack--two {
+ min-width: 36px;
+ }
+
+ &.AvatarStack--three-plus {
+ min-width: 46px;
+ }
+}
+
+.AvatarStack-body {
+ display: flex;
+ background: $bg-white;
+
+ .avatar {
+ position: relative;
+ z-index: 2;
+ display: flex;
+ width: 20px;
+ height: 20px;
+ box-sizing: content-box;
+ margin-right: -11px;
+ background-color: $bg-white;
+ border-right: $border-width $border-style $white;
+ border-radius: 2px;
+ transition: margin 0.1s ease-in-out;
+
+ &:first-child {
+ z-index: 3;
+ }
+
+ &:last-child {
+ z-index: 1;
+ }
+
+ // stylelint-disable selector-max-type
+ img {
+ border-radius: 2px;
+ }
+ // stylelint-enable selector-max-type
+
+ // Account for 4+ avatars
+ &:nth-child(n+4) {
+ display: none;
+ opacity: 0;
+ }
+ }
+
+ &:hover {
+ .avatar {
+ margin-right: 3px;
+ }
+
+ .avatar:nth-child(n+4) {
+ display: flex;
+ opacity: 1;
+ }
+
+ .avatar-more {
+ display: none !important;
+ }
+ }
+}
+
+.avatar.avatar-more {
+ z-index: 1;
+ margin-right: 0;
+ background: $gray-100;
+
+ &::before,
+ &::after {
+ position: absolute;
+ display: block;
+ height: 20px;
+ content: "";
+ border-radius: 2px;
+ outline: $border-width $border-style $white;
+ }
+
+ &::before {
+ width: 17px;
+ background: $gray-200;
+ }
+
+ &::after {
+ width: 14px;
+ background: $gray-300;
+ }
+}
+
+// Right aligned variation
+
+.AvatarStack--right {
+ .AvatarStack-body {
+ right: 0;
+ flex-direction: row-reverse;
+
+ &:hover .avatar {
+ margin-right: 0;
+ margin-left: 3px;
+ }
+ }
+
+ .avatar.avatar-more {
+ background: $gray-300;
+
+ &::before {
+ width: 5px;
+ }
+
+ &::after {
+ width: 2px;
+ background: $gray-100;
+ }
+ }
+
+ .avatar {
+ margin-right: 0;
+ margin-left: -11px;
+ border-right: 0;
+ border-left: $border-width $border-style $white;
+ }
+}
diff --git a/modules/primer-avatars/stories.js b/modules/primer-avatars/stories.js
index cf9aec8a7a..4759855490 100644
--- a/modules/primer-avatars/stories.js
+++ b/modules/primer-avatars/stories.js
@@ -26,6 +26,43 @@ storiesOf('Avatars', module)
))
+.add('AvatarStack', () => (
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+