@workday/canvas-kit-docs 14.0.0-alpha.1156-next.0 → 14.0.0-alpha.1162-next.0

package/dist/mdx/tokens/TokenMigrationOverview.mdx

@@ -0,0 +1,148 @@
+import {AIIndicator, DownloadLLMFile} from '@workday/canvas-kit-docs';
+import {StorybookInformationHighlight} from './StorybookInformationHighlight';
+
+
+# Canvas Kit Token Migration Guide: Moving to `@workday/canvas-tokens-web`
+
+Canvas Kit v10+ introduces a new token system that replaces the old JavaScript-based tokens from
+`@workday/canvas-kit-react/tokens` with CSS variables from `@workday/canvas-tokens-web`.
+
+## Why Migrate?
+
+- **Better Performance**: CSS variables eliminate the runtime cost of Emotion's dynamic styling
+- **Enhanced Theming**: System and brand tokens provide semantic, themeable values
+- **Cross-Platform Consistency**: Single source of truth for design tokens across web, iOS, and
+  Android
+- **Future-Proofing**: Aligns with modern CSS capabilities and Canvas Kit's long-term direction
+
+## LLM Assisted Migration <AIIndicator />
+
+We provide a **LLM migration mapping file** (`llm-token-migration.txt`) specifically designed for
+use with LLM-based code assistants (such as [Cursor](https://www.cursor.so/) or similar tools). This
+file is not intended for direct human reference or team documentation, but rather as structured
+input for LLMs to automate and assist with your token migration process.
+
+> The LLM migration file is regularly updated to reflect the latest token mappings and best
+> practices.
+> For more details, see other sections of this migration guide.
+
+This file contains a comprehensive mapping of old Canvas Kit token usages to their new equivalents
+in `@workday/canvas-tokens-web`, along with migration tips and examples and formatted for optimal
+LLM consumption.
+
+**How to use:**
+
+- **View raw file**: Open the file in a new tab to see the complete migration mapping
+- **Download as txt**: Save the file locally to upload or paste into your LLM/code assistant
+- **Use with LLM**: Provide the raw content to your LLM/code assistant as context for automated
+  migration
+
+<DownloadLLMFile
+  rawFileLink="https://raw.githubusercontent.com/Workday/canvas-kit/master/modules/docs/llm-txt/llm-token-migration.txt"
+  filename="llm-token-migration-13.2.0.txt"
+/>
+
+## Core Principles
+
+### Token Hierarchy
+
+The new token system is organized into three categories:
+
+- **Base Tokens**: Fundamental values (colors, measurements) - use sparingly
+- **System Tokens**: Semantic, themeable values - **use these in most cases**
+- **Brand Tokens**: Tenant/brand-specific customization values
+
+### CSS Variables Requirement
+
+Unlike the old JavaScript tokens, the new tokens are CSS variables that must be wrapped in `var()`
+for the browser to understand them.
+
+**The Fundamental Change**: Raw (hex, px, etc) values → CSS variables wrapped in `var()`
+
+```javascript
+// Old approach - Raw values
+import {space} from '@workday/canvas-kit-react/tokens';
+// padding: '1rem'
+const styles = {padding: space.s};
+
+// New approach - CSS variables with var()
+import {system} from '@workday/canvas-tokens-web';
+// padding: 'var(--cnvs-sys-space-x4)'
+const styles = {padding: `var(${system.space.x4})`};
+
+// New approach - Using cssVar utility (recommended) and fallback
+import {cssVar} from '@workday/canvas-kit-styling';
+// padding: 'var(--cnvs-sys-space-x4, 1rem)'
+const styles = {padding: cssVar(system.space.x4, '1rem')};
+```
+
+### Styling Utilities
+
+Canvas Kit provides styling utilities such as `createStyles`, `createStencil`, `cssVar`, and calc
+functions to handle CSS variable syntax automatically.
+
+<StorybookInformationHighlight
+  title="Why use styling utilities?"
+  description="Styling utilities automatically wrap tokens in <code>var()</code> and provide fallbacks for better browser support. They also ensure consistent token usage across your components."
+  link="/?path=/docs/styling-getting-started-overview--docs"
+  linkText="Learn more about styling utilities"
+/>
+
+## Best Practices
+
+<br />
+
+### Prefer System Tokens
+
+Use system tokens over base tokens whenever possible for better theming support:
+
+```javascript
+// Good - Semantic and themeable
+backgroundColor: system.color.bg.default;
+
+// Avoid - Hard-coded base value
+backgroundColor: base.frenchVanilla100;
+```
+
+### Use Complete Type Levels
+
+Instead of mixing individual type properties, use complete type level tokens:
+
+```javascript
+// Good - Consistent type styling
+...system.type.body.medium
+
+// Avoid - Mixing individual properties
+fontSize: system.fontSize.body.medium,
+fontWeight: system.fontWeight.regular,
+lineHeight: '1.5'
+```
+
+### Leverage Styling Utilities
+
+Always use `createStyles` and `cssVar` for proper CSS variable handling:
+
+```javascript
+// Good - Proper CSS variable wrapping
+const styles = createStyles({
+  padding: system.space.x4,
+});
+
+// Avoid - Manual CSS variable handling
+const styles = {
+  padding: `var(${system.space.x4})`,
+};
+```
+
+### Convert Pixel Values
+
+Use `px2rem` for pixel-based values to maintain consistency:
+
+```javascript
+import {px2rem} from '@workday/canvas-kit-styling';
+
+const styles = createStyles({
+  border: `solid ${px2rem(1)}`,
+  borderColor: system.color.border.container,
+});
+```

package/index.ts

@@ -1,3 +1,5 @@
+export {AIIndicator} from './lib/AIIndicator';
+export {DownloadLLMFile} from './lib/DownloadLLMFile';
 export {ExampleCodeBlock} from './lib/ExampleCodeBlock';
 export * from './lib/specs';
 export * from './lib/Specifications';

package/lib/AIIndicator.tsx

@@ -0,0 +1,22 @@
+import {StatusIndicator} from '@workday/canvas-kit-preview-react/status-indicator';
+import {system} from '@workday/canvas-tokens-web';
+import {sparkleSingleSmallIcon} from '@workday/canvas-system-icons-web';
+import {systemIconStencil} from '@workday/canvas-kit-react/icon';
+
+export const AIIndicator = () => {
+  return (
+    <>
+      <StatusIndicator
+        className="sb-unstyled indicator"
+        cs={{
+          background: system.color.bg.ai.default,
+          color: system.color.fg.ai,
+          [systemIconStencil.vars.color]: system.color.fg.ai,
+        }}
+      >
+        <StatusIndicator.Icon icon={sparkleSingleSmallIcon} />
+        <StatusIndicator.Label>AI Content</StatusIndicator.Label>
+      </StatusIndicator>
+    </>
+  );
+};

package/lib/DownloadLLMFile.tsx

@@ -0,0 +1,69 @@
+import {Card} from '@workday/canvas-kit-react/card';
+import {ExternalHyperlink, SecondaryButton} from '@workday/canvas-kit-react/button';
+import {downloadIcon, fileIcon} from '@workday/canvas-system-icons-web';
+import {SystemIcon} from '@workday/canvas-kit-react';
+import {createStencil} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+type DownloadLLMFileProps = {
+  rawFileLink: string;
+  filename: string;
+};
+
+const flexBlock = createStencil({
+  vars: {
+    gap: system.space.x1,
+  },
+  base: ({gap}) => ({
+    display: 'flex',
+    alignItems: 'center',
+    gap,
+    code: {
+      fontFamily: system.fontFamily.mono,
+      padding: system.space.x1,
+      paddingInline: system.space.x2,
+      backgroundColor: system.color.bg.alt.softer,
+      borderRadius: system.shape.half,
+    },
+  }),
+});
+
+export const DownloadLLMFile = ({rawFileLink, filename}: DownloadLLMFileProps) => {
+  const handleDownload = async () => {
+    try {
+      const response = await fetch(rawFileLink);
+      const content = await response.text();
+
+      const blob = new Blob([content], {type: 'text/plain'});
+      const url = URL.createObjectURL(blob);
+
+      const link = document.createElement('a');
+      link.href = url;
+      link.download = filename;
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+
+      URL.revokeObjectURL(url);
+    } catch (error) {
+      console.error('Failed to download file:', error);
+    }
+  };
+
+  return (
+    <Card className="sb-unstyled" cs={{boxShadow: 'none', borderStyle: 'dashed'}}>
+      <Card.Body cs={{display: 'grid', gridTemplateColumns: '1fr auto', alignItems: 'center'}}>
+        <div {...flexBlock()}>
+          <SystemIcon icon={fileIcon} />
+          <code>{filename}</code>
+        </div>
+        <div {...flexBlock({gap: system.space.x4})}>
+          <ExternalHyperlink href={rawFileLink}>See raw file</ExternalHyperlink>
+          <SecondaryButton icon={downloadIcon} size="small" onClick={handleDownload}>
+            Download LLM File
+          </SecondaryButton>
+        </div>
+      </Card.Body>
+    </Card>
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "14.0.0-alpha.1156-next.0",
+  "version": "14.0.0-alpha.1162-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -45,11 +45,11 @@
     "@emotion/styled": "^11.6.0",
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1156-next.0",
-    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1156-next.0",
-    "@workday/canvas-kit-react": "^14.0.0-alpha.1156-next.0",
-    "@workday/canvas-kit-styling": "^14.0.0-alpha.1156-next.0",
-    "@workday/canvas-system-icons-web": "^3.0.0",
+    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1162-next.0",
+    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1162-next.0",
+    "@workday/canvas-kit-react": "^14.0.0-alpha.1162-next.0",
+    "@workday/canvas-kit-styling": "^14.0.0-alpha.1162-next.0",
+    "@workday/canvas-system-icons-web": "^3.0.35",
     "@workday/canvas-tokens-web": "3.0.0-alpha.5",
     "markdown-to-jsx": "^7.2.0",
     "react-syntax-highlighter": "^15.5.0",
@@ -61,5 +61,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "e5711be8fa7794a67a880925c1b582a1abbcfbf6"
+  "gitHead": "542377d8b4fcaf4fa3f40e4ef6ef66a8524e8de9"
 }