update atomics/color documentation (#718)

* update atlas atomics/color page with better information * update * also add this to the accessibility tests * Update .vscode/semantic-color-table.code-snippets Co-authored-by: Ming Ho <94572161+homing1@users.noreply.github.com> * Update site/src/atomics/colors.md Co-authored-by: Ming Ho <94572161+homing1@users.noreply.github.com> * Update site/src/atomics/colors.md Co-authored-by: Ming Ho <94572161+homing1@users.noreply.github.com> * Update .vscode/semantic-color-table.code-snippets Co-authored-by: Ben Myers <benmyers@microsoft.com> --------- Co-authored-by: Ming Ho <94572161+homing1@users.noreply.github.com> Co-authored-by: Ben Myers <benmyers@microsoft.com>
microsoft · Nov 12, 2024 · 2fc0420 · 2fc0420
1 parent d6a1806
commit 2fc0420
Show file tree

Hide file tree

Showing 5 changed files with 286 additions and 28 deletions.
diff --git a/.changeset/itchy-spoons-sort.md b/.changeset/itchy-spoons-sort.md
@@ -0,0 +1,5 @@
+---
+'@microsoft/atlas-site': minor
+---
+
+Update color atomics documentation.
diff --git a/.vscode/semantic-color-table.code-snippets b/.vscode/semantic-color-table.code-snippets
@@ -0,0 +1,50 @@
+{
+	// Place your atlas-design workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and
+	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope
+	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is
+	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
+	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.
+	// Placeholders with the same ids are connected.
+	// Example:
+	"Semantic color table": {
+		"scope": "markdown",
+		"prefix": "Semantic",
+		"body": [
+			"<table class=\"table\">",
+			"\t<caption>",
+			"\t\t${1:textlabel} color classes",
+			"\t</caption>",
+			"\t<thead>",
+			"\t\t<tr>",
+			"\t\t\t<th>Background color /<br>Text color</th>",
+			"\t\t\t<th>Text class</th>",
+			"\t\t\t<th>Background class</th>",
+			"\t\t</tr>",
+			"\t</thead>",
+			"\t<tbody>",
+			"\t\t<tr class=\"background-color-${2:textlabel}-invert color-${2:textlabel}\">",
+			"\t\t\t<td>${1:textlabel} invert /<br>${1:textlabel}</td>",
+			"\t\t\t<td><code>.color-${2:textlabel}</code></td>",
+			"\t\t\t<td><code>.background-color-${2:textlabel}-invert</code></td>",
+			"\t\t</tr>",
+			"\t\t<tr class=\"background-color-${2:textlabel}-light\" style=\"color: var(--theme-${2:textlabel}-dark)\">",
+			"\t\t\t<td>${1:textlabel} light /<br> ${1:textlabel} dark</td>",
+			"\t\t\t<td>N/A</td>",
+			"\t\t\t<td><code>.background-color-${2:textlabel}-light</code></td>",
+			"\t\t</tr>",
+			"\t\t<tr class=\"background-color-${2:textlabel} color-${2:textlabel}-invert\">",
+			"\t\t\t<td>${1:textlabel} /<br>${1:textlabel} invert</td>",
+			"\t\t\t<td><code>.color-${2:textlabel}-invert</code></td>",
+			"\t\t\t<td><code>.background-color-${2:textlabel}</code></td>",
+			"\t\t</tr>",
+			"\t\t<tr class=\"background-color-${2:textlabel}-dark color-${2:textlabel}-invert\">",
+			"\t\t\t<td>${1:textlabel} dark /<br>${1:textlabel} invert</td>",
+			"\t\t\t<td><code>.color-${2:textlabel}-invert</code></td>",
+			"\t\t\t<td><code>.background-color-${2:textlabel}-dark</code></td>",
+			"\t\t</tr>",
+			"\t</tbody>",
+			"</table>"
+		],
+                "description": "A table that can showcase a semantic color"
+	}
+}
diff --git a/integration/config/page.ts b/integration/config/page.ts
@@ -29,6 +29,7 @@ export const pages: LocalPageConfig[] = [
 	// { pathname: '/atomics/spacing.html', name: 'Atomics/spacing', routes },
 	// { pathname: '/atomics/typography.html', name: 'Atomics/typography', routes },
 	// { pathname: '/atomics/width.html', name: 'Atomics/width', routes },
+	{ pathname: '/atomics/colors.html', name: 'Atomics/colors', routes },
 	{ pathname: '/components/breadcrumbs.html', name: 'Components/breadcrumbs', routes },
 	{ pathname: '/components/button.html', name: 'Components/button', routes },
 	{ pathname: '/components/checkbox.html', name: 'Components/checkbox', routes },

diff --git a/site/src/atomics/colors.md b/site/src/atomics/colors.md
@@ -0,0 +1,229 @@
+---
+title: Color
+description: Color and background-color related atomic css classes for the Atlas Design System
+template: standard
+classType: Atomics
+classPrefixes:
+  - color
+  - background-color
+---
+
+# Color Atomics
+
+Atlas has CSS classes that allow you to easily apply themed background and text colors. Change the site's theme to see how each looks in different themes.
+
+## Accessibility concerns
+
+Atlas components ensure accessible text-to-background color contrast ratios. However, when applying specific colors yourself via atomics, always remember to test contrast.
+
+## Text colors
+
+Atlas has three themed text colors.
+
+<table class="table">
+	<caption>
+		Text color classes
+	</caption>
+	<thead>
+		<tr>
+			<th>Text color</th>
+			<th>Text class</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr class="color-text">
+			<td>Text</td>
+			<td><code>.color-text</code></td>
+		</tr>
+		<tr class="color-text-subtle">
+			<td>Text subtle</td>
+			<td><code>.color-text-subtle</code></td>
+		</tr>
+		<tr class="color-text-invert background-color-alternate">
+			<td>Text invert</td>
+			<td><code>.color-text-invert</code></td>
+		</tr>
+	</tbody>
+</table>
+
+## Background colors
+
+Atlas has five themed (non-semantic) background colors.
+
+<table class="table">
+	<caption>
+		Body color classes
+	</caption>
+	<thead>
+		<tr>
+			<th>Background color</th>
+			<th>Background class</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr class="background-color-body">
+			<td>Body</td>
+			<td><code>.background-color-body</code></td>
+		</tr>
+		<tr class="background-color-body-medium">
+			<td>Body medium</td>
+			<td><code>.background-color-body-medium</code></td>
+		</tr>
+		<tr class="background-color-body-accent">
+			<td>Body accent</td>
+			<td><code>.background-color-body-accent</code></td>
+		</tr>
+		<tr class="background-color-alternate color-text-invert">
+			<td>Alternate</td>
+			<td><code>.background-color-alternate</code></td>
+		</tr>
+		<tr class="background-color-alternate-medium color-text-invert">
+			<td>Alternate medium </td>
+			<td><code>.background-color-alternate-medium</code></td>
+		</tr>
+	</tbody>
+</table>
+
+## Semantic colors
+
+Semantic colors are themed colors that vary depending on the active theme. They have names that pertain to their usage. Generally speaking, these are the colors used to paint components too.
+
+<table class="table">
+	<caption>
+		Primary color classes
+	</caption>
+	<thead>
+		<tr>
+			<th>Background color /<br>Text color</th>
+			<th>Font class</th>
+			<th>Background class</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr class="background-color-primary-invert color-primary">
+			<td>Primary invert /<br>Primary</td>
+			<td><code>.color-primary</code></td>
+			<td><code>.background-color-primary-invert</code></td>
+		</tr>
+		<tr class="background-color-primary-light" style="color: var(--theme-primary-dark)">
+			<td>Primary light /<br> Primary dark</td>
+			<td>N/A</td>
+			<td><code>.background-color-primary-light</code></td>
+		</tr>
+		<tr class="background-color-primary color-primary-invert">
+			<td>Primary /<br>Primary invert</td>
+			<td><code>.color-primary-invert</code></td>
+			<td><code>.background-color-primary</code></td>
+		</tr>
+		<tr class="background-color-primary-dark color-primary-invert">
+			<td>Primary dark /<br>Primary invert</td>
+			<td><code>.color-primary-invert</code></td>
+			<td><code>.background-color-primary-dark</code></td>
+		</tr>
+	</tbody>
+</table>
+
+<table class="table">
+	<caption>
+		Success color classes
+	</caption>
+	<thead>
+		<tr>
+			<th>Background color /<br>Text color</th>
+			<th>Font class</th>
+			<th>Background class</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr class="background-color-success-invert color-success">
+			<td>Success invert /<br>Success</td>
+			<td><code>.color-success</code></td>
+			<td><code>.background-color-success-invert</code></td>
+		</tr>
+		<tr class="background-color-success-light" style="color: var(--theme-success-dark)">
+			<td>Success light /<br> Success dark</td>
+			<td>N/A</td>
+			<td><code>.background-color-success-light</code></td>
+		</tr>
+		<tr class="background-color-success color-success-invert">
+			<td>Success /<br>Success invert</td>
+			<td><code>.color-success-invert</code></td>
+			<td><code>.background-color-success</code></td>
+		</tr>
+		<tr class="background-color-success-dark color-success-invert">
+			<td>Success dark /<br>Success invert</td>
+			<td><code>.color-success-invert</code></td>
+			<td><code>.background-color-success-dark</code></td>
+		</tr>
+	</tbody>
+</table>
+
+<table class="table">
+	<caption>
+		Info color classes
+	</caption>
+	<thead>
+		<tr>
+			<th>Background color /<br>Text color</th>
+			<th>Font class</th>
+			<th>Background class</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr class="background-color-info-invert color-info">
+			<td>Info invert /<br>Info</td>
+			<td><code>.color-info</code></td>
+			<td><code>.background-color-info-invert</code></td>
+		</tr>
+		<tr class="background-color-info-light" style="color: var(--theme-info-dark)">
+			<td>Info light /<br> Info dark</td>
+			<td>N/A</td>
+			<td><code>.background-color-info-light</code></td>
+		</tr>
+		<tr class="background-color-info color-info-invert">
+			<td>Info /<br>Info invert</td>
+			<td><code>.color-info-invert</code></td>
+			<td><code>.background-color-info</code></td>
+		</tr>
+		<tr class="background-color-info-dark color-info-invert">
+			<td>Info dark /<br>Info invert</td>
+			<td><code>.color-info-invert</code></td>
+			<td><code>.background-color-info-dark</code></td>
+		</tr>
+	</tbody>
+</table>
+
+<table class="table">
+	<caption>
+		Danger color classes
+	</caption>
+	<thead>
+		<tr>
+			<th>Background color /<br>Text color</th>
+			<th>Font class</th>
+			<th>Background class</th>
+		</tr>
+	</thead>
+	<tbody>
+		<tr class="background-color-danger-invert color-danger">
+			<td>Danger invert /<br>Danger</td>
+			<td><code>.color-danger</code></td>
+			<td><code>.background-color-danger-invert</code></td>
+		</tr>
+		<tr class="background-color-danger-light" style="color: var(--theme-danger-dark)">
+			<td>Danger light /<br> Danger dark</td>
+			<td>N/A</td>
+			<td><code>.background-color-danger-light</code></td>
+		</tr>
+		<tr class="background-color-danger color-danger-invert">
+			<td>Danger /<br>Danger invert</td>
+			<td><code>.color-danger-invert</code></td>
+			<td><code>.background-color-danger</code></td>
+		</tr>
+		<tr class="background-color-danger-dark color-danger-invert">
+			<td>Danger dark /<br>Danger invert</td>
+			<td><code>.color-danger-invert</code></td>
+			<td><code>.background-color-danger-dark</code></td>
+		</tr>
+	</tbody>
+</table>
diff --git a/site/src/tokens/colors.md b/site/src/tokens/colors.md
@@ -7,31 +7,4 @@ token: colors
 
 # Colors
 
-Atlas currently supports three themes out of the box.
-
-## Background Colors
-
-<div class="padding-xl background-color-body">
-	<p class="font-weight-bold font-size-h4 margin-bottom-xs">body</p>
-	<p><code>.background-color-body</code></p>
-</div>
-
-<div class="padding-xl background-color-body-medium">
-	<p class="font-weight-bold font-size-h4 margin-bottom-xs">body-medium</p>
-	<p><code>.background-color-body-medium</code></p>
-</div>
-
-<div class="padding-xl background-color-body-accent">
-	<p class="font-weight-bold font-size-h4 margin-bottom-xs">body-accent</p>
-	<p><code>.background-color-body-accent</code></p>
-</div>
-
-<div class="padding-xl background-color-alternate color-text-invert">
-	<p class="font-weight-bold font-size-h4 margin-bottom-xs">alternate</p>
-	<p><code>.background-color-alternate</code></p>
-</div>
-
-<div class="padding-xl background-color-alternate-medium color-text-invert margin-bottom-xl">
-	<p class="font-weight-bold font-size-h4 margin-bottom-xs">alternate-medium</p>
-	<p><code>.background-color-alternate-medium</code></p>
-</div>
+Atlas currently supports three themes out of the box. See [atomics/colors](../atomics/colors.md) for examples.