@workday/canvas-kit-mcp 15.0.0-alpha.0051-next.0 → 15.0.0-alpha.0060-next.0

package/dist/lib/tokens/color-contrast.md

@@ -0,0 +1,116 @@
+# Color Contrast
+
+Color pairings should pass contrast requirements to ensure content is readable for everyone. Colors
+in the palette are built with contrast baked in to make it simple to create accessible color
+combinations.
+
+Canvas believes that designing for accessible experience benefits everyone. Improved contrast
+improves readability in bright sunlight, low-quality displays, and for users experiencing temporary
+vision impairment. Using the color system can help reduce the guesswork in choosing colors and
+ensure contrast ratios when applied.
+
+## Understanding Contrast
+
+Contrast measures the difference in brightness between two colors, ensuring that content is
+perceivable and readable against backgrounds. WCAG 2.1 guidelines specify a minimum contrast ratio
+of 4.5:1 for text, 3:1 for interactive elements, and 7:1 for high contrast. The
+[global palette](/guidelines/color/color-palette) and [tonal scale](/guidelines/color/color-scale)
+are designed with target contrast ratios baked in, making it straightforward to achieve compliant
+color combinations without a separate calculator.
+
+![Color contrast demonstration showing different step differences and their compliance levels](color-contrast-overview.png)
+
+![Text examples showing AA compliance (4.5:1) with black text on light gray, and AAA compliance (7:1) with white text on dark blue backgrounds](color-contrast-text-on-white.png)
+
+## Usage Guidance
+
+1. **Use [color roles](/guidelines/color/color-roles)** to guarantee accessibility through design
+   tokens.
+2. **Use the contrast framework**: If you need to choose colors from directly from the palette, make
+   sure to choose accessible color combinations. Use the
+   [contrast framework](#accessible-color-combinations) to make it easy to select accessible pairs
+   just from the step number.
+3. **Check your designs** against color-blindness and low-vision simulators to get a feel for what
+   your design might look like in different scenarios.
+4. **Avoid the use of color alone** to communicate information.
+
+![Color role examples showing bg-primary and text-primary automatically maintaining proper contrast ratios across light and dark themes](color-contrast-color-blind.png)
+
+## Accessible Color Combinations
+
+Colors are graded using a 15 step tonal scale. Each step is assigned to a number that represents the
+lightness of that color relative to other colors in the scale. For example, 0 is the lightest color
+in the scale (white), and 1000 is the darkest color (black). A 500 color would have a lightness
+value between the two, with lighter and darker variations on both sides. To determine if a color
+will pass contrast, compare step numbers and the difference between the two.
+
+Regular text requires a 500+ step difference to achieve the 4.5:1 ratio needed for AA compliance.
+For enhanced accessibility, text can use a 700+ step difference to achieve the 7:1 ratio that
+exceeds AAA compliance standards. For non-text contrast, a 400+ step difference is needed (if both
+colors have step numbers greater than 200+|)
+
+### Overview
+
+| **Content**  | **WCAG Level** | **Target Ratio** | **Step Difference** | **Example**                |
+| ------------ | -------------- | ---------------- | ------------------- | -------------------------- |
+| **Text**     | AA             | 4.5:1            | 500+                | `slate-100` on `slate-600` |
+| **Text**     | AAA            | 7:1              | 700+                | `slate-100` on `slate-800` |
+| **Non-text** | AA             | 3:1              | 400+ (>200)         | `blue-600` on `blue-100`   |
+| **Non-text** | AAA            | 4.5:1            | 500+                | `blue-100` on `blue-600`   |
+
+### Text Contrast
+
+Normal sized text should have at least at 4.5:1 contrast to meet Level AA compliance. A difference
+of 500 or more between steps guarentees it passes text contrast guidelines.
+
+![Step difference examples showing 500+ differences guarantee 4.5:1 text contrast across various background and text color combinations](color-contrast-text-between.png)
+
+| **Background** | **Foreground Step** | **Step Difference** | **Compliance Level** |
+| -------------- | ------------------- | ------------------- | -------------------- |
+| 0(white)       | 600                 | 600                 | AA Text              |
+| 100            | 600                 | 500                 | AA Text              |
+| 200            | 700                 | 500                 | AA Text              |
+| 300            | 800                 | 500                 | AA Text              |
+| 400            | 900                 | 500                 | AA Text              |
+| 500            | 1000 (black)        | 500                 | AA Text              |
+
+### Non-text Contrast
+
+Interactive elements and non-decorative visuals (icons) should have a contrast of 3:1 to meet Level
+AA compliance.
+
+A difference of 400 or more between steps guarantees a contrast of 3:1 for steps greater than 200.
+
+![Interactive elements showing buttons, form inputs, and icons meeting 3:1 contrast requirements with 400+ step differences](color-contrast-nontext-between.png)
+
+| **Background** | **Foreground Step** | **Step Difference** | **Compliance Level** |
+| -------------- | ------------------- | ------------------- | -------------------- |
+| 0(white)       | 500                 | 500                 | AA Non-text          |
+| 25             | 500                 | 475                 | AA Non-text          |
+| 200            | 600                 | 400                 | AA Non-text          |
+| 300            | 700                 | 400                 | AA Non-text          |
+| 400            | 800                 | 400                 | AA Non-text          |
+| 500            | 900                 | 400                 | AA Non-text          |
+| 600            | 1000 (black)        | 400                 | AA Non-text          |
+
+### High Contrast (> 7:1)
+
+Level AAA contrast should be targeted when you are designing for low vision or colorblindness. For
+both text and non-text contrast, this means the target difference is increased (text increases to
+700+, non-text increases to 500+).
+
+![High contrast interface examples showing AAA compliance with 7:1+ ratios for enhanced accessibility and low vision support](color-contrast-nontext-on-white.png)
+
+| **Background** | **AA Contrast** | **AAA Contrast** | **AA Difference** | **AAA Difference** |
+| -------------- | --------------- | ---------------- | ----------------- | ------------------ |
+| 0(white)       | 700             | 500              | 700               | 500                |
+| 100            | 800             | 600              | 700               | 500                |
+| 200            | 900             | 700              | 700               | 500                |
+| 300            | 1000 (black)    | 800              | 700               | 500                |
+| 400            | 1000 (black)    | 900              | 600               | 500                |
+| 500            | 0(white)        | 0(white)         | 500               | 500                |
+| 600            | 0(white)        | 0(white)         | 600               | 600                |
+| 700            | 0(white)        | 100              | 700               | 600                |
+| 800            | 100             | 200              | 700               | 600                |
+| 900            | 200             | 300              | 700               | 600                |
+| 1000 (black)   | 300             | 400              | 700               | 600                |

package/dist/lib/tokens/color-palette.md

@@ -0,0 +1,141 @@
+# Color Palette
+
+## Global Palette
+
+The Canvas palette is Workday's shared color palette meant for use across all products and
+platforms. It includes 11 colors and 2 neutrals, each with 13 shades.
+
+Colors are designed in the okLCH (lightness, chroma, hue) color space to feel perceptually balanced,
+meaning that colors with the same step value appear similar in brightness. This uniformity makes
+accessible contrast ratios more predictable between steps and helps create smooth transitions when
+switching between different contexts, such as themes and modes.
+
+The global palette extends Workday's brand colors to create functional tones and tints meant for use
+in interface and product design. Colors are organized into color families ('blue', 'red', 'green')
+and a tonal scale from lightest (0) to darkest (1000), with each step serving a specific role in the
+interface.
+
+Color scales follow a gradual progression in vibrancy, peaking at the midpoint, before decreasing
+again. This progression creates softer surface colors at the tailends, and more vibrant accents in
+the middle.
+
+### Accent Colors
+
+Accent colors are saturated colors - like blue, red, orange, purple. Accent colors are used to draw
+attention towards them and should be used sparingly, and for a specific purpose.
+
+<Do>
+
+- Use accent colors to highlight important information
+- Use existing color roles to inform selection
+- Use accent colors sparingly
+- for important actions, alerts, or states
+
+</Do>
+
+<Dont>
+
+- Avoid decorative use of accent colors
+- Avoid applying accent colors to secondary or supporting content
+
+</Dont>
+
+### Neutral Colors
+
+Neutrals are greyscale colors, used for backgrounds, foregrounds, or as a base for alpha colors. The
+palette includes 2 neutrals meant for different purposes.
+
+- Slate is a tinted neutral built from Workday's brand blue. It's meant for secondary backgrounds,
+  borders, and text for subtle styling that pairs well with brand accents.
+- Neutral is an achromatic greyscale with no hue or chroma, from white to black. It's meant for
+  consistent contrast against backgrounds, such as prose text.
+
+<Do>
+
+- Use Neutral for prose and structural content - Use Slate for secondary UI elements, borders, and
+  text
+
+</Do>
+
+<Dont>
+
+- Use Neutral and Slate interchangeably
+
+</Dont>
+
+### Alpha Colors
+
+Alpha colors are colors with transparency that adaptive dynamically to background colors. This
+creates a natural layering effect on the background without requiring new color definitions for each
+background.
+
+<Do>
+
+- Use alpha colors when elements need to adapt to different backgrounds - Use alpha colors in a
+  consistent way throughout the experience - Ensure sufficient contrast for underlying content
+
+</Do>
+
+## Brand Palette
+
+Brand colors represent Workday's core brand and identity. Reserve use for brand moments, marketing
+materials, and other use cases specific to the Workday brand.
+
+For more information, see
+[Workday's brand guidelines](https://brand.workday.com/document/89#/-/workday-brand-guide).
+
+## Product Palette
+
+The product palette is a subset of the global palette meant for use when designing Workday features
+and interfaces. Colors in the product palette are assigned
+[color roles](/guidelines/color/color-roles) through the use of
+[design tokens](/styles/tokens/color).
+
+### Color Roles
+
+Color roles assign a purpose to colors in the palette, specifying when and how to use that color.
+When building Workday interfaces, use system design tokens to ensure that color roles are
+consistently applied throughout the admin. For example, the `positive` color role is used to
+indicate success and task completion.
+
+To learn more about color roles, see [Color Roles](/guidelines/color/color-roles).
+
+### Design Tokens
+
+Design tokens represent a design decision as structured data. Tokens store visual properties like
+color and spacing in a platform-agnostic format, such as JSON. Those decisions are then transformed
+into platform specific pacakges in a format ready to be consumed by each platform.
+
+Defining colors as tokens removes the need to redefine colors for each platform. Instead, colors are
+defined in a single location and distributed to each platform, enabling more consistent,
+maintainable, and systemic change over time.
+
+#### Base Tokens
+
+Base tokens are static colors whose values do not change. All colors in the
+[global palette](#global-palette) are represented as base tokens. Base colors are organized using a
+tonal scale, from lightest to darkest.
+
+#### Brand Tokens
+
+Brand tokens are used to enable brand/tenant level theming. This means that colors are subject to
+change depending on the customer's brand.
+
+They are not connected to system tokens, which are meant for application-wide use.
+
+For a full list of brand tokens, see [Brand Tokens](/styles/tokens/color#brand-color-tokens).
+
+#### System Tokens
+
+System tokens applies a role to a color. For example, `sys.color.bg.critical.default` can be read as
+"the default background color for critical elements".
+
+System colors are mapped to Base colors. For example, `sys.color.bg.critical.default` is mapped to
+`base.palette.red.600`. This is how theming is applied. Creating a new theme means that the value of
+the system color is swapping with another color.
+
+Approaching color this way makes the process part of a larger system instead of an isolated choice.
+Instead of asking "what color should this be?", the question becomes "what role does this element
+play in the interface?".
+
+For a full list of system tokens, see [System Tokens](/styles/tokens/color#system-color-tokens).