workday/canvas-kit/sana-canvas-kit-component-selection

Canvas Kit deprecation & package tiers

Never introduce or recommend anything carrying `@deprecated`. Verify in installed node_modules before choosing an export or prop.

REQUIRED SUB-SKILL: /sana-canvas-kit-version. Deprecation status is version-specific — run it first so you know which generation's rules apply before checking JSDoc.

Which token → /sana-canvas-kit-tokens. How to style (cs, stencils) → /sana-canvas-kit-styling. Building a new component → /sana-canvas-kit-builder. Choosing between components for a use case → /sana-canvas-kit-design-principles.

Package tiers

Preview and Labs are not “always better.” Use them only when the export you need is @deprecated and the JSDoc points there.

Figma pills / badges: Preview StatusIndicator (emphasis="low") is the usual Canvas Kit stand-in, but many Figma frames use a custom pill treatment. Confirm the node is a library StatusIndicator (or Code Connect) before reaching for it — otherwise rebuild the custom chrome with tokens/Flex.

`@workday/canvas-kit-labs-react` is not installed here. If JSDoc points to Labs, first check

whether the component has since landed in Main (as SidePanel did). If it only exists in Labs,

say so rather than adding the package.

Core rules

1. Check installed versions — deprecations vary by release; always read the installed source,

not static tables alone.

1. JSDoc is the source of truth — @deprecated tag + replacement message on the export or prop.
2. Follow the chain — Main → Preview → Labs → removal.
3. Match nearby imports — prefer the tier the file already uses when both are valid.
4. Style props on `Box`/`Flex` are deprecated — use cs + createStyles/createStencil

(/sana-canvas-kit-styling). Do not teach the migration here.

1. Legacy kit tokens are deprecated — never @workday/canvas-kit-react/tokens; use

@workday/canvas-tokens-web (/sana-canvas-kit-tokens).

What can be deprecated

Workflow

- [ ] Inventory imports in the target file(s)
- [ ] Candidate export/prop
- [ ] Confirm export is NOT @deprecated in node_modules
- [ ] Confirm each prop is NOT @deprecated
- [ ] If deprecated, follow JSDoc replacement (tier or prop)
- [ ] Run the validation script on changed files

Verify exports

rg -n "export (const|function|class|interface|type) SymbolName" \
  node_modules/@workday/canvas-kit-react \
  node_modules/@workday/canvas-kit-preview-react \
  node_modules/@workday/canvas-kit-labs-react

Read the JSDoc above the export. If @deprecated, do not use it.

Verify props

rg -n "interface \w+Props" node_modules/@workday/canvas-kit-react/<component> -A30
rg -B5 "@deprecated" node_modules/@workday/canvas-kit-react/<component>

Follow the replacement

Validate

From the project root:

node skills/sana-canvas-kit-component-selection/scripts/check-deprecated-usage.mjs <file-or-dir>

(If skills are installed under .cursor/skills/ or .claude/skills/, adjust the path prefix.)

Red flags

Confirm each against installed JSDoc before acting:

• Main Switch, Radio, RadioGroup, StatusIndicator in new UI
• AccentIcon, AppletIcon, LabelText
• Style props on Box/Flex (margin, padding, display, …)
• boxStyleFn, styled, mergeStyles, theme / useTheme
• @workday/canvas-kit-react/tokens or canvas.*
• Ignoring @deprecated because “it still works”

Additional resources

• Hint tables: references.md (verify in node_modules first)
• How to style after leaving style props: /sana-canvas-kit-styling
• Which token path to use: /sana-canvas-kit-tokens
• Accessibility (labels, keyboard, ARIA): /sana-canvas-kit-accessibility