doc: color foundation update (#669)

build.washingtonpost.com/components/Layout/Layout.js

@@ -56,7 +56,7 @@ const Container = styled("main", {
   margin: "0 auto",
   marginTop: "$125",
   [customNotSmBreakpoint]: {
-    maxWidth: "1028px",
+    maxWidth: "900px",
   },
   [customSmBreakpoint]: {
     padding: "0 $100",

build.washingtonpost.com/components/Markdown/Components/InlineImage.js

@@ -8,19 +8,26 @@ export default function InlineImage({
   width,
   height,
   src,
+  cushion,
   ...rest
 }) {
   const ImageContainer = styled("div", {
     maxWidth: `${maxWidth}px`,
-
     padding: "$100",
+    variants: {
+      cushion: {
+        none: {
+          padding: 0,
+        },
+      },
+    },
   });
 
   const inlineImageCSS = css({
     aspectRatio: `${width}/${height}`,
   });
   return (
-    <ImageContainer>
+    <ImageContainer cushion={cushion}>
       <Image
         className={inlineImageCSS()}
         {...rest}

build.washingtonpost.com/components/Markdown/Examples/ColorSamples.jsx

@@ -26,6 +26,10 @@ const PaletteGrid = styled("div", {
   gridTemplateColumns: "30px repeat(12, 1fr)",
   gridTemplateRows: "repeat(11, 1fr)", // Adjusted to match yMapping length
   gap: "$025",
+  "@sm": {
+    transformOrigin: "left",
+    transform: "scale(.9)",
+  },
 });
 
 const Swatch = styled("div", {

build.washingtonpost.com/components/Markdown/Examples/ThemeTokens.jsx

@@ -4,7 +4,7 @@ import { styled, theme, Box } from "@washingtonpost/wpds-ui-kit";
 const Layout = styled("div", {
   display: "grid",
   gap: theme.space["050"],
-  gridTemplateColumns: "repeat(auto-fit, 250px)",
+  gridTemplateColumns: "repeat(auto-fill, 292px)",
 });
 const Container = styled("div", {
   width: "100%",

build.washingtonpost.com/components/Markdown/Styling.js

@@ -5,7 +5,7 @@
 import React from "react";
 import { Header } from "./Components/headers";
 import CustomLink from "./Components/link";
-import { styled, theme, Box, Button } from "@washingtonpost/wpds-ui-kit";
+import { styled, theme, Box, Button, Tabs } from "@washingtonpost/wpds-ui-kit";
 import {
   List,
   ListItem,
@@ -63,7 +63,6 @@ export const P = styled("p", {
   paddingBottom: "$050",
   fontFamily: "$meta",
   fontWeight: "$light",
-  maxWidth: "767px",
   "& > code": {
     fontFamily: "monospace",
     backgroundColor: theme.colors.subtle,
@@ -146,7 +145,7 @@ const components = {
   Change: Change,
   h1: ({ children }) => <Header as="h1">{children}</Header>,
   h2: ({ children }) => (
-    <Header id={children} css={{ paddingBottom: "$100" }} as="h2">
+    <Header id={children} css={{ paddingBottom: "$025" }} as="h2">
       {children}
     </Header>
   ),
@@ -248,6 +247,19 @@ const components = {
   YoutubeEmbed: dynamic(() => import("./Components/YouTubeEmbed")),
   StyleConverter: dynamic(() => import("./Components/StyleConverter")),
   Anatomy: dynamic(() => import("./Components/Anatomy")),
+  TabsRoot: ({ defaultValue, children }) => (
+    <Tabs.Root defaultValue={defaultValue}>{children}</Tabs.Root>
+  ),
+  TabsList: ({ children }) => <Tabs.List>{children}</Tabs.List>,
+  TabsTrigger: ({ value, children }) => (
+    <Tabs.Trigger value={value}>{children}</Tabs.Trigger>
+  ),
+  TabsContent: ({ value, children }) => (
+    <Tabs.Content value={value}>
+      <BR />
+      {children}
+    </Tabs.Content>
+  ),
 };
 
 export default components;

build.washingtonpost.com/components/Typography/Description.js

@@ -6,5 +6,4 @@ export const Description = styled("p", {
   fontWeight: theme.fontWeights.light,
   lineHeight: theme.lineHeights["150"],
   marginBlock: 0,
-  maxWidth: "767px",
 });

build.washingtonpost.com/docs/foundations/color.mdx

@@ -4,73 +4,173 @@ title: Color
 description: Color token values are defined by their context. There are two contexts we currently support a "light" and "dark" context. Toggle the sun/moon in the top right of the site to see each context.
 ---
 
-<BR />
+<TabsRoot defaultValue="Overview">
+<TabsList>
+<TabsTrigger value="Overview">Overview</TabsTrigger>
+{/* WORK WITH NEWS DESIGN - <TabsTrigger value="Color Use">Color Use</TabsTrigger> */}
+<TabsTrigger value="Color Tokens">Tokens</TabsTrigger>
+</TabsList>
 
-## Table of contents
+<TabsContent value="Overview">
 
-- [Introduction to Our Color Palette](/foundations/color#Introduction%20to%20Our%20Color%20Palette)
-- [Theme and Semantic Tokens](/foundations/color#Theme%20and%20Semantic%20Tokens)
-- [Color tokens](/foundations/color#Color%20tokens)
+<ColorSamples />
 
----
+<BR />
 
-<ColorSamples />
+---
 
 <BR />
+## General Concepts 
+
+Color themes and device color modes aren't synonymous; themes are tailored to apps, while modes are system-wide settings that impact device theming.
+
+{/* Start of Grid Section */}
+
+<Box css={{display:"flex",alignItems:"start",flexDirection:"row", gap:"$150","@media (max-width: 600px)":{flexDirection:"column-reverse"}}}>
+ {/*Column one of Grid  */}
+<Container css={{display:"flex",alignItems:"start",justifyContent:"start",width:"100%"}}>
+    <InlineSVG
+        path="/img/foundations/color/tints-shades.svg"
+    />
+</Container>
+{/* Column two of Grid */}
+<Box css={{width:"100%"}}>
+
+#### Color
 
-Note: In the graphic, the number in each color swatch is the contrast against our `background` color. For accessibility, large text should have at least a 3:1 ratio for AA compliance, and small text should have at least 4.5:1 for AA and 7:1 for AAA compliance. See WCAG for details.
+Used generically to refer to named colors (e.g., blue).
+
+#### Tint
+
+A lighter value of a color.
+
+#### Shade
+
+A darker value of a color.
+
+#### Tone
+
+A less saturated version of a color. Alternatively used as a synonym for tints or shades.
+
+    </Box>
+
+</Box>
+{/* End of Grid Section */}
 
 <BR />
 
 ---
 
-## Introduction to Our Color Palette
+## Contrast Ratio
+
+The measurable difference in lightness between two comparative using the WCAG relative luminance formula.
 
-Our color palette is designed to cater to the diverse needs of our product's design requirements, providing a comprehensive range of colors.
+{/* Start of Grid Section */}
 
-#### Recommended Usage
+<Box css={{display:"flex",alignItems:"start",flexDirection:"row", gap:"$150","@media (max-width: 600px)":{flexDirection:"column-reverse"}}}>
+ {/*Column one of Grid  */}
+<Container css={{minHeight:352,display:"flex",alignItems:"center",justifyContent:"start",width:"100%"}}>
+    <InlineSVG
+        title="*The number 4.74:1 reflects the contrast ratio against the target background gray700"
+        path="/img/foundations/color/contrast-ratio.svg"
+    />
+</Container>
+{/* Column two of Grid */}
+<Box css={{width:"100%"}}>
 
-While our palette offers a variety of colors suitable for a
-wide array of applications within our product, we strongly recommend using our theme
-tokens. These tokens are specifically designed to ensure that colors are applied
-with the correct intention and assignment, particularly in contexts where light and
-dark themes are utilized.
+#### Target contrast ratio
 
-#### How to Reference Color Tokens
+The desired contrast ratio between two color values when one of the color values is generated by a color tool.
+For accessibility, large text should have at least a 3:1 ratio for AA compliance, and small text should have at least 4.5:1 for AA and 7:1 for AAA compliance. WPDS strives to maintain AAA (contrast ratio of 7:1).
+See WCAG for details.
 
-Color tokens can be referenced by combining their color group and scale. This system allows for easy identification and application of color values within your projects. For example:
+    </Box>
 
-- `gray100`
-- `red300`
-- `teal600`
+</Box>
+{/* End of Grid Section */}
 
 <BR />
 
-**Note:** The -static modifier preserves the color token's consistency across light and dark contexts. Its usage should be limited within the scope of our product to maintain design coherence.
+---
+
+## Semantic Structure
+
+The following is the semantic structure of our theme tokens.
 
-#### Using our tokens in code
+<Container>
+  <InlineSVG
+    title="*The number 4.74:1 reflects the contrast ratio against the target background gray700"
+    path="/img/foundations/color/semantics.svg"
+  />
+</Container>
+
+---
 
-When you need to apply colors from the WPDS theme to your components, start by importing the `theme` object from the WPDS UI kit package. This enables you to use the theme's predefined color values in a type-safe manner, ensuring consistency across your application and adherence to the design system.
-For example:
+## Color modes
 
-`import { theme } from "@washingtonpost/wpds-ui-kit";`
-`theme.colors.background //Reference to the token`
+It's important to differentiate between color themes and device color modes. Color themes reflect specific design preferences, whereas device color modes are part of the operating system settings that influence the entire device's appearance. Typically, devices offer two modes: light mode and dark mode.
 
 <BR />
 
----
+{/* Start of Grid Section */}
+
+<Box
+  css={{
+    display: "flex",
+    alignItems: "start",
+    flexDirection: "row",
+    gap: "$150",
+    "@media (max-width: 600px)": { flexDirection: "column-reverse" },
+  }}
+>
+  {/*Column one of Grid  */}
+  <Box
+    css={{
+      display: "flex",
+      alignItems: "start",
+      justifyContent: "start",
+      width: "100%",
+    }}
+  >
+    <InlineImage
+      cushion="none"
+      width={518}
+      height={452}
+      src="/img/foundations/color/lightmode.svg"
+    />
+  </Box>
+  {/* Column two of Grid */}
+  <Box
+    css={{
+      display: "flex",
+      alignItems: "start",
+      justifyContent: "start",
+      width: "100%",
+    }}
+  >
+    <InlineImage
+      cushion="none"
+      width={518}
+      height={452}
+      src="/img/foundations/color/darkmode.svg"
+    />
+  </Box>
+</Box>
+{/* End of Grid Section */}
+
+<BR />
 
-## Theme and Semantic Tokens
+---
 
-Our theme tokens follow a semantic and predictable structure comprising three parts:
+<BR />
 
-- **Role:** This defines the purpose of the token within the UI.
-- **Modifier (Optional):** This denotes a variant, change, or subset of the role, such as -subtle\*.
-- **State (Optional):** This indicates the token's state within the UI.
+## Theme Tokens
 
-#### Definition
+The theme palette is an abstraction that assigns color across the product with intention, creating an alias for color use. In our design framework, "on" colors are used on top of primary, secondary, surface, background, or error colors. For example, "on primary" is a color used over a primary color. These colors are mainly for text, icons, and strokes, though they can be used on surfaces as well.
 
-**subtle\*:** The subtle modifier ensures that the color token remains the same color across light and dark contexts.
+<Container css={{ flexDirection: "column", padding: "$300" }}>
+  <InlineSVG path="/img/foundations/color/breakdown.svg" />
+</Container>
 
 <BR />
 
@@ -80,10 +180,30 @@ Our theme tokens follow a semantic and predictable structure comprising three pa
 
 ---
 
-## Color tokens
+<BR />
 
-<ColorTokenTable />
+## Surfaces
 
-<BR />
+The relationship between surface, elevation and shadow. Surface, background, and portal colors typically don't represent brand:
+Surface and portal colors affect surfaces of components, such as cards, and menus, but will change in dark mode to create elevation & hierarchy.
+The background color appears behind scrollable content. The baseline background, surface, and portal color is gray700.
+
+{" "}
+
+<InlineImage
+  cushion="none"
+  width={1066}
+  height={637}
+  src="/img/foundations/color/surface.svg"
+/>
 
-<BR size="xl" />
+<BR/>
+</TabsContent>
+
+<TabsContent value="Color Tokens">
+  <ColorTokenTable />
+</TabsContent>
+
+</TabsRoot>
+
+<BR />