[DSYS-317] Mark the legacy color tokens as deprecated

.changeset/forty-pumpkins-decide.md

@@ -0,0 +1,5 @@
+---
+'@sumup/design-tokens': minor
+---
+
+Deprecated the legacy color tokens. Migrate to semantic color tokens instead: refer to the [Figma documentation](https://www.figma.com/file/OgPQeoNZ2QoY7hZvy0ybk2/%F0%9F%8C%88-COLOR-TOKENS?node-id=913%3A3903&t=b9BsTOJnzKDomZ9E-4) (internal link) for context. The new tokens are available as CSS custom properties, listed in the [Circuit UI theme documentation](https://circuit.sumup.com/?path=/docs/features-theme--docs).

packages/design-tokens/types/index.ts

@@ -13,76 +13,279 @@
  * limitations under the License.
  */
 
+/**
+ * @deprecated
+ *
+ * The Circuit UI theme is moving from color scales (e.g. `g900`) to semantic
+ * colors (e.g. `fg-success`). This makes theme customizations easier and more
+ * reliable, and enables theming for sub-brands or for supporting multiple
+ * color modes. For detailed documentation on the new semantic colors, refer to
+ * the [Figma documentation](https://www.figma.com/file/OgPQeoNZ2QoY7hZvy0ybk2/%F0%9F%8C%88-COLOR-TOKENS?node-id=913%3A3903&t=b9BsTOJnzKDomZ9E-4).
+ *
+ * Additionally, color tokens are moving from the JS theme (exported from
+ * `@sumup/design-tokens`) to CSS custom properties, declared in
+ * `@sumup/circuit-ui`'s `BaseStyles` component (v6.1+). For a list of all
+ * available CSS custom properties, refer to the [Circuit UI theme documentation](https://circuit.sumup.com/?path=/docs/features-theme--docs).
+ */
 export type Colors = {
+  /**
+   * @deprecated
+   */
   white: string;
+  /**
+   * @deprecated
+   */
   black: string;
   // Neutrals
+  /**
+   * @deprecated
+   */
   n100: string;
+  /**
+   * @deprecated
+   */
   n200: string;
+  /**
+   * @deprecated
+   */
   n300: string;
+  /**
+   * @deprecated
+   */
   n500: string;
+  /**
+   * @deprecated
+   */
   n700: string;
+  /**
+   * @deprecated
+   */
   n800: string;
+  /**
+   * @deprecated
+   */
   n900: string;
   // Blues
+  /**
+   * @deprecated
+   */
   b100: string;
+  /**
+   * @deprecated
+   */
   b200: string;
+  /**
+   * @deprecated
+   */
   b300: string;
+  /**
+   * @deprecated
+   */
   b400: string;
+  /**
+   * @deprecated
+   */
   b500: string;
+  /**
+   * @deprecated
+   */
   b700: string;
+  /**
+   * @deprecated
+   */
   b900: string;
   // Greens
+  /**
+   * @deprecated
+   */
   g100: string;
+  /**
+   * @deprecated
+   */
   g200: string;
+  /**
+   * @deprecated
+   */
   g300: string;
+  /**
+   * @deprecated
+   */
   g500: string;
+  /**
+   * @deprecated
+   */
   g700: string;
+  /**
+   * @deprecated
+   */
   g900: string;
   // Violets
+  /**
+   * @deprecated
+   */
   v100: string;
+  /**
+   * @deprecated
+   */
   v200: string;
+  /**
+   * @deprecated
+   */
   v300: string;
+  /**
+   * @deprecated
+   */
   v500: string;
+  /**
+   * @deprecated
+   */
   v700: string;
+  /**
+   * @deprecated
+   */
   v900: string;
   // Oranges
+  /**
+   * @deprecated
+   */
   o100: string;
+  /**
+   * @deprecated
+   */
   o200: string;
+  /**
+   * @deprecated
+   */
   o300: string;
+  /**
+   * @deprecated
+   */
   o500: string;
+  /**
+   * @deprecated
+   */
   o700: string;
+  /**
+   * @deprecated
+   */
   o900: string;
   // Yellows
+  /**
+   * @deprecated
+   */
   y100: string;
+  /**
+   * @deprecated
+   */
   y200: string;
+  /**
+   * @deprecated
+   */
   y300: string;
+  /**
+   * @deprecated
+   */
   y500: string;
+  /**
+   * @deprecated
+   */
   y700: string;
+  /**
+   * @deprecated
+   */
   y900: string;
   // Reds
+  /**
+   * @deprecated
+   */
   r100: string;
+  /**
+   * @deprecated
+   */
   r200: string;
+  /**
+   * @deprecated
+   */
   r300: string;
+  /**
+   * @deprecated
+   */
   r500: string;
+  /**
+   * @deprecated
+   */
   r700: string;
+  /**
+   * @deprecated
+   */
   r900: string;
   // Primary
+  /**
+   * @deprecated
+   */
   p100: string;
+  /**
+   * @deprecated
+   */
   p200: string;
+  /**
+   * @deprecated
+   */
   p300: string;
+  /**
+   * @deprecated
+   */
   p400: string;
+  /**
+   * @deprecated
+   */
   p500: string;
+  /**
+   * @deprecated
+   */
   p700: string;
+  /**
+   * @deprecated
+   */
   p900: string;
   // Misc
+  /**
+   * @deprecated
+   */
   shadow: string;
+  /**
+   * @deprecated
+   *
+   * You should likely use `--cui-bg-overlay` instead.
+   */
   overlay: string;
+  /**
+   * @deprecated
+   *
+   * You should likely use `--cui-bg-normal` instead.
+   */
   bodyBg: string;
+  /**
+   * @deprecated
+   *
+   * You should likely use `--cui-fg-normal` instead.
+   */
   bodyColor: string;
+  /**
+   * @deprecated
+   */
   info: string;
+  /**
+   * @deprecated
+   */
   confirm: string;
+  /**
+   * @deprecated
+   */
   alert: string;
+  /**
+   * @deprecated
+   */
   notify: string;
 };
 
@@ -192,6 +395,20 @@ export type ZIndex = {
 };
 
 export interface Theme {
+  /**
+   * @deprecated
+   *
+   * The Circuit UI theme is moving from color scales (e.g. `g900`) to semantic
+   * colors (e.g. `fg-success`). This makes theme customizations easier and more
+   * reliable, and enables theming for sub-brands or for supporting multiple
+   * color modes. For detailed documentation on the new semantic colors, refer to
+   * the [Figma documentation](https://www.figma.com/file/OgPQeoNZ2QoY7hZvy0ybk2/%F0%9F%8C%88-COLOR-TOKENS?node-id=913%3A3903&t=b9BsTOJnzKDomZ9E-4).
+   *
+   * Additionally, color tokens are moving from the JS theme (exported from
+   * `@sumup/design-tokens`) to CSS custom properties, declared in
+   * `@sumup/circuit-ui`'s `BaseStyles` component (v6.1+). For a list of all
+   * available CSS custom properties, refer to the [Circuit UI theme documentation](https://circuit.sumup.com/?path=/docs/features-theme--docs).
+   */
   colors: Colors;
   spacings: Spacings;
   iconSizes: IconSizes;