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

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

@@ -0,0 +1,277 @@
+# Color Scale
+
+Colors are organized into scales with steps from 0 (lightest) to 1000 (darkest). Colors are designed
+to be perceptually balanced, ensuring consistent lightness across color families. Colors with the
+same step number serve similar purposes, regardless of hue.
+
+![Complete color scale showing 0-1000 progression across multiple color families demonstrating consistent lightness relationships](color-scale-overview.png)
+
+Scales are designed using the okLCH color space to create perceptually balanced colors. Color peak
+in vividness at the midpoint (500) and decrease at the tail-ends to create softer surface colors and
+more vibrant accents.
+![Vividness curve diagram showing how color intensity peaks at step 500 and decreases toward extremes](color-scale-vividness-curve.png)
+
+**Amber Exception:** Due to amber's natural color properties, its chroma peaks at lighter values
+(around step 300) rather than 500. This means amber uses step 400 for primary colors to maintain
+accessibility compliance while preserving vibrancy.
+
+![Amber vividness exception showing higher chroma around step 300–400](color-scale-400-amber.png)
+
+![Perceptual uniformity demonstration showing how step 500 appears equally bright across all color families](color-scale-500.png)
+
+<Do>
+
+- Apply consistent steps for similar UI elements across all color families
+- When choosing color combinations, use the [contrast framework](/guidelines/color/color-contrast)
+  to ensure accessible contrast ratios
+- Use steps to create visual hierarchy
+
+</Do>
+
+<Dont>
+
+- Use steps for different purposes
+- Mix steps randomly, always consider visual hierarchy
+- Ignore contrast requirements when choosing steps
+
+</Dont>
+
+![Visual hierarchy example showing how step 100 applies consistently to secondary buttons across blue, green, and red color families](color-scale-100-to-300.png)
+
+## Step Guidelines
+
+Choose the right step for your UI elements:
+
+![Step usage examples showing how different steps apply to common interface elements](color-scale-step-examples.png)
+
+| **Step** | **Primary Use Case**  | **Description**                                                   |
+| -------- | --------------------- | ----------------------------------------------------------------- |
+| 0        | Page backgrounds      | Lightest color (white in light mode, black in dark mode)          |
+| 25       | Input backgrounds     | Subtle differentiation that maintains text contrast               |
+| 50       | Subtle backgrounds    | Light surface backgrounds that don't compete with primary content |
+| 100      | Secondary backgrounds | Clear hierarchy between subtle and primary content                |
+| 200      | Divider borders       | Gentle separation, less harsh than stronger borders               |
+| 300      | Container borders     | Structural definition while remaining lightweight                 |
+| 400      | Disabled states       | Reduced contrast for disabled input borders and text              |
+| 500      | Input borders         | Meets 3:1 contrast for interactive boundaries                     |
+| 600      | Accent text           | Balances vividness with readability on white backgrounds          |
+| 700      | Hover states          | Increased weight provides interaction feedback                    |
+| 800      | Body text             | Comfortable contrast for extended reading                         |
+| 900      | Heading text          | Strong contrast creates content hierarchy                         |
+| 950      | Display text          | Maximum contrast demands immediate attention                      |
+| 975      | Dark mode backgrounds | Reserved for dark mode page backgrounds                           |
+| 1000     | Maximum contrast      | Strongest emphasis for overlays, rarely used                      |
+
+### Steps 0–100 - Page Backgrounds
+
+![Interface showing default white page background (step 0) and subtle gray alternative background (step 50) in side-by-side layouts](color-scale-page-backgrounds.png)
+
+Use the default page background for most use cases, especially if colors will be used on top of it.
+
+A secondary option is needed when subtle differentiaton is needed against the background.
+
+<Do>
+
+- Use default background for most page layouts
+- Choose subtle alternatives when background differentiation is needed
+- Apply very light backgrounds for disabled and error states
+
+</Do>
+
+<Dont>
+
+- Use subtle backgrounds when color overlays will be present
+- Apply alternative backgrounds without clear purpose
+
+</Dont>
+
+| **Color**  | **Usage**                          |
+| ---------- | ---------------------------------- |
+| `base.0`   | Default background color for pages |
+| `slate.50` | Subtle background color for pages  |
+
+### Step 50 - Subtle Backgrounds
+
+Light surfaces that don't compete with primary content.
+
+![Step 50 subtle background examples](color-scale-50.png)
+
+<Do>
+
+- Use for low emphasis status indicators
+- Create subtle content zones that don't compete with primary content
+- Apply when minimal visual presence is desired
+
+</Do>
+
+<Dont>
+
+- Use when content needs to stand out or grab attention
+- Apply to elements requiring clear visibility
+
+</Dont>
+
+### Step 100 - Secondary Backgrounds
+
+Clear hierarchy between subtle and primary content.
+
+![Step 100 secondary background examples](color-scale-100-to-300.png)
+
+<Do>
+
+- Use for secondary button backgrounds
+- Apply to hover states for light content
+- Choose for UI elements needing moderate prominence
+
+</Do>
+
+<Dont>
+
+- Use for primary actions or main content
+- Apply when subtle emphasis is sufficient
+
+</Dont>
+
+### Step 200, 300 - Surface Borders
+
+Visual structures for non-interactive surfaces.
+
+<FormattedImage caption="Step 200 - Gentle separation between content.">
+
+![Step 200 divider borders examples](color-scale-200-to-300-borders.png)
+
+</FormattedImage>
+
+<FormattedImage caption="Step 300** - Container borders indicating modular sections.">
+
+![Step 300 container borders examples](color-scale-300.png)
+
+</FormattedImage>
+
+<Do>
+
+- Use lighter borders for list dividers and lightweight boundaries
+- Apply stronger borders for container definition and modular sections
+- Choose based on visual separation needs
+
+</Do>
+
+<Dont>
+
+- Use for interactive elements requiring higher contrast
+- Apply to elements needing accessibility compliance
+
+</Dont>
+
+### Step 400, 500 - Interactive Elements
+
+<FormattedImage caption="Step 400 - Disabled states with reduced contrast.">
+
+![Step 400 disabled foregrounds/borders examples](color-scale-400.png)
+
+</FormattedImage>
+
+<FormattedImage caption="Step 500 - Interactive boundaries meeting 3:1 contrast. Midpoint with peak saturation for vibrant accents.">
+
+![Step 500 input borders examples](color-scale-500.png)
+
+</FormattedImage>
+
+<Do>
+
+- Use reduced contrast for disabled states and non-interactive elements
+- Apply accessible contrast for input borders and interactive elements
+- Meet minimum WCAG 2.1 AA compliance requirements
+- Leverage peak saturation for vibrant accent colors
+
+</Do>
+
+<Dont>
+
+- Use disabled state colors for interactive elements
+- Apply interactive colors below minimum contrast requirements
+- Use low contrast colors for accessibility-critical elements
+
+</Dont>
+
+### Step 600, 700 - Accent Backgrounds
+
+Vibrant interactive elements with guarenteed readability with inverse text or top of default
+backgrounds (4.5:1 contrast).
+
+![Step 600–800 accents and 700 hover examples](color-scale-600-800.png)
+![Step 700 hover examples](color-scale-700-hover.png)
+
+<Do>
+
+- Use for interactive accent colors, like PrimaryButton backgrounds
+- Apply to link text, error text, and hint text on default backgrounds
+- Use the next step (700) for hover states and 800 for active states
+
+</Do>
+
+<Dont>
+
+- Apply to secondary UI or prose text - Use when something more subtle is more appropriate
+
+</Dont>
+
+### Step 800, 900, 950 - Text Hierarchy
+
+Text contrast levels for content hierarchy and readability.
+
+![Step 800–950 text hierarchy examples](color-scale-800-950.png)
+
+**Step 800** - Comfortable contrast for extended reading and body text. **Step 900** - Strong
+contrast for headings and important text. **Step 950** - Maximum contrast for display text and hero
+headlines.
+
+<Do>
+
+- Use on prose content
+- Match level of contrast to typographic hierarchy
+
+</Do>
+
+<Dont>
+
+- Use for secondary or instructional text (use 600 instead)
+- Use for accent text, like links (use 600 intead)
+
+</Dont>
+
+### Step 975 - Dark Mode Backgrounds
+
+Reserved for dark mode page backgrounds to maintain consistent color relationships.
+
+![Step 975 dark mode backgrounds](color-scale-975.png)
+
+<Do>
+
+- Use exclusively for dark mode page backgrounds
+
+</Do>
+
+<Dont>
+
+- Use in light mode interfaces
+
+</Dont>
+
+### Step 1000 - Overlay Backgrounds
+
+Strongest emphasis color for alpha overlays and modal dialogs.
+
+![Step 1000 overlay backgrounds](color-scale-1000.png)
+
+<Do>
+
+- Use for alpha overlays and modal dialog scrims
+
+</Do>
+
+<Dont>
+
+- Use as solid color in interfaces
+
+</Dont>

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

@@ -0,0 +1,130 @@
+# Color Tokens
+
+Design tokens represent design decisions as reusable, named values that drive consistency across
+product teams. Tokens work as a shared language between design and development teams, replacing
+isolated color decisions with systematic choices that carry meaning and adapt to different contexts.
+
+![Design token system diagram showing base palette mapping to system tokens across different platforms](color-tokens-dev-handoff.png)
+
+## Token Types
+
+| **Token Type** | **Example Name**                     | **Purpose**            |
+| -------------- | ------------------------------------ | ---------------------- |
+| Base Palette   | `blue-50`, `gray-100`                | Raw color values       |
+| System Tokens  | `bg.default`, `text.primary.default` | Intent-driven UI usage |
+
+### Base Palette
+
+Raw `oklch` colors from the [global palette](/guidelines/color/color-palette), categorized in color
+families using the [tonal scale](/guidelines/color/color-scale) from 0 to 1000. Each number
+represents lightness, creating perceptual uniformity across families.
+
+### System Colors
+
+Purpose-driven names that describe intended use rather than appearance. Follow the
+`[property].[role].[modifier]` pattern and map to base tokens based on theme.
+
+## Token Naming System
+
+**`[property].[role].[modifier]`**
+
+![Token naming structure diagram showing element, role, and state components with examples](color-tokens-naming-structure.png)
+
+1. **Property**: What gets colored
+2. **Role**: Semantic purpose
+3. **Modifier**: Intensity or state (optional)
+
+### Property Types
+
+| **Property** | **Description**                               | **Examples**                             |
+| ------------ | --------------------------------------------- | ---------------------------------------- |
+| `bg`         | Background colors for surfaces and containers | `bg.default`, `bg.primary.default`       |
+| `text`       | Text and content colors                       | `text.default`, `text.primary.default`   |
+| `border`     | Border and divider colors                     | `border.input.default`, `border.divider` |
+| `icon`       | Icon-specific colors when different from text | `icon.default`, `icon.primary.default`   |
+| `fg`         | Foreground colors for content elements        | `fg.default`, `fg.primary.default`       |
+| `shadow`     | Shadow colors for depth and elevation         | `shadow.default`, `shadow.1`             |
+| `static`     | Static colors that don't change with themes   | `static.blue.default`, `static.white`    |
+
+### Role Types
+
+| **Role**      | **Usage**                                     | **Examples**                                   |
+| ------------- | --------------------------------------------- | ---------------------------------------------- |
+| `default`     | Main content and standard elements            | `bg.default`, `text.default`                   |
+| `primary`     | Main brand and primary actions                | `bg.primary.default`, `text.primary.default`   |
+| `positive`    | Success states and positive feedback          | `bg.positive.default`, `text.positive.default` |
+| `critical`    | Error states and destructive actions          | `bg.critical.default`, `text.critical.default` |
+| `caution`     | Warning states and caution messages           | `bg.caution.default`, `text.caution.default`   |
+| `info`        | Informational messages and neutral feedback   | `bg.info.default`, `text.info.default`         |
+| `alt`         | Secondary surfaces and alternate states       | `bg.alt.default`, `bg.alt.soft`                |
+| `muted`       | Secondary content and subtle elements         | `bg.muted.default`, `fg.muted.default`         |
+| `contrast`    | High contrast elements                        | `bg.contrast.default`, `fg.contrast.default`   |
+| `ai`          | AI-powered features and content               | `bg.ai.default`, `text.ai`                     |
+| `focus`       | Keyboard navigation indicators                | `border.primary.default` (focus)               |
+| `disabled`    | Non-interactive and unavailable elements      | `text.disabled`, `icon.disabled`               |
+| `inverse`     | High contrast text on dark backgrounds        | `text.inverse`, `icon.inverse`                 |
+| `hint`        | Placeholder and helper text                   | `text.hint`                                    |
+| `input`       | Form field borders and interactive elements   | `border.input.default`                         |
+| `container`   | Surfaces that exist on top of page background | `border.container`                             |
+| `divider`     | Content separators between sections           | `border.divider`                               |
+| `transparent` | Invisible elements for spacing                | `bg.transparent.default`                       |
+| `translucent` | Semi-transparent overlays                     | `bg.translucent`                               |
+| `overlay`     | Modal scrims and background dimming           | `bg.overlay`                                   |
+
+### Modifier Variations
+
+| **Modifier** | **Usage**                                | **Examples**            |
+| ------------ | ---------------------------------------- | ----------------------- |
+| `default`    | Standard intensity or base state         | `bg.primary.default`    |
+| `soft`       | Reduced intensity or subtle appearance   | `bg.primary.soft`       |
+| `softer`     | More reduced intensity                   | `bg.primary.softer`     |
+| `softest`    | Minimum intensity or lightest appearance | `bg.primary.softest`    |
+| `strong`     | Increased intensity or emphasis          | `bg.primary.strong`     |
+| `stronger`   | Higher intensity or more emphasis        | `bg.primary.stronger`   |
+| `strongest`  | Maximum intensity or strongest emphasis  | `static.blue.strongest` |
+| `disabled`   | Disabled element states                  | `text.disabled`         |
+| `inverse`    | Inverted color for contrast              | `text.inverse`          |
+
+## Theming and Adaptation
+
+Tokens enable flexible theming by separating purpose from appearance. System tokens maintain
+consistent names across themes while colors adapt to match visual style.
+
+![Light and dark theme comparison showing same tokens with different color values](color-tokens-theming.png)
+
+Create multiple theme variations—light/dark modes, brand customizations, high-contrast
+themes—without changing design logic or token names.
+
+## Benefits of Tokens
+
+**Consistency:** Clear relationships between colors and purposes make interfaces predictable.
+
+**Efficiency:** Centralized decisions enable systematic updates across all platforms automatically.
+
+**Collaboration:** Teams focus on semantic meaning rather than debating specific values.
+
+## Working with Tokens
+
+### Figma
+
+Canvas tokens sync to Figma Libraries as organized color variables. Designers search by name, apply
+to designs, and receive automatic updates when values change.
+
+![Figma color variables showing organized system tokens with search functionality](color-tokens-figma.png)
+
+### Design-to-Development Handoff
+
+Shared vocabulary between teams. Designers apply variables to their designs, developers view those
+designs in Figma's Developer Mode. Tokens can be viewed as either CSS variables, SwiftUI view
+modifiers, or Jetpack Compose theme properties - making it easy for developers to choose correct
+colors for the platform they build for.
+
+![Design-to-development workflow showing Figma design with token annotations matching React component code implementation](color-tokens-dev-handoff.png)
+
+### Brand Customization
+
+Brand tokens let you change the brand expression by modifying those token values without changing
+semantic structure. This enables white-label solutions, reskinning UI without needing to completely
+redesign the interfaces.
+
+![Brand customization showing same interface with different brand color tokens applied](color-tokens-customization.png)