add new recommendations for color and typography (#5350)

documentation-site/examples/use-styletron/basic.tsx

@@ -1,10 +1,10 @@
-import React from 'react';
-import {useStyletron} from 'baseui';
+import React from "react";
+import { useStyletron } from "baseui";
 
 function UseStyletronExample() {
   const [css, theme] = useStyletron();
   return (
-    <div className={css({color: theme.colors.accent})}>
+    <div className={css({ color: theme.colors.backgroundAccent })}>
       This is a blue div
     </div>
   );

documentation-site/pages/components/typography.mdx

@@ -1,3 +1,5 @@
+import { Notification, KIND } from "baseui/notification";
+
 import Example from "../../components/example";
 import Layout from "../../components/layout";
 import Exports from "../../components/exports";
@@ -9,6 +11,15 @@ import Text from "examples/typography/text.tsx";
 
 export default Layout;
 
+<Notification
+  overrides={{ Body: { style: { width: "auto" } } }}
+  kind={KIND.warning}
+>
+  These typography components are built on top of the Block component, which we
+  no longer recommend. Refer to the <a href="/guides/styling/">Styling</a> guide
+  to understand how to use Base Web typography in your components.
+</Notification>
+
 # Typography
 
 A set of text block components for an out-of-the-box path to the BaseUI font standard.

documentation-site/pages/components/use-styletron.mdx

@@ -50,9 +50,9 @@ on the given component:
 
 To understand overrides better, go [here](/guides/understanding-overrides/).
 
-## Custom themes and Flow type
+## Custom themes and types
 
-The `styled` and `withStyle` functions imported from `baseui` provide flow type support for the
+The `styled` and `withStyle` functions imported from `baseui` provide type support for the
 default [theme shape](/guides/theming/#theme-properties). However, if you create a custom theme with additional fields,
 flow will show an error. To help, baseui exports two utility functions `createThemedStyled` and
 `createThemedWithStyle`. These will return their respective functions with a provided theme type.
@@ -68,27 +68,27 @@ Doing so saves you from needing to import the custom theme type around. See belo
 +  createThemedUseStyletron,
  } from 'baseui';
 
- type CustomThemeT = {myBlue: string, myRed: string};
+ type CustomTheme = {myBlue: string, myRed: string};
 
 // you'll likely want to import these functions from a relative path in your application
-+const themedStyled = createThemedStyled<CustomThemeT>();
-+const themedWithStyle = createThemedWithStyle<CustomThemeT>();
-+const themedUseStyletron = createThemedUseStyletron<CustomThemeT>();
++const themedStyled = createThemedStyled<CustomTheme>();
++const themedWithStyle = createThemedWithStyle<CustomTheme>();
++const themedUseStyletron = createThemedUseStyletron<CustomTheme>();
 
- type PropsT = {
+ type Props = {
    $active: boolean
--  $theme: CustomThemeT
+-  $theme: CustomTheme
  };
 
--const First = styled<PropsT>('div', props => {
-+const First = themedStyled<PropsT>('div', props => {
+-const First = styled<Props>('div', props => {
++const First = themedStyled<Props>('div', props => {
    return {
      backgroundColor: props.$active ? props.$theme.colors.myBlue : props.$theme.colors.myRed,
    };
  });
 
--const Second = withStyle<PropsT>('div', props => {
-+const Second = themedWithStyle<PropsT>(First, props => {
+-const Second = withStyle<Props>('div', props => {
++const Second = themedWithStyle<Props>(First, props => {
    return {
      color: props.$active ? props.$theme.colors.myBlue : props.$theme.colors.myRed,
    };
@@ -99,7 +99,7 @@ const Third = () => {
 + const [css, theme] = themedUseStyletron();
 
 return (
-- <div className={css({color: theme.colors.primary})}>
+- <div className={css({color: theme.colors.contentPrimary})}>
 + <div className={css({color: theme.myBlue)}>
     test
   </div>

documentation-site/pages/getting-started/learn.mdx

@@ -26,7 +26,7 @@ export default () => {
       href="/my-link"
       className={css({
         fontSize: "20px",
-        color: theme.colors.primary,
+        color: theme.colors.contentPrimary,
       })}
     >
       Custom Link

documentation-site/pages/guides/colors.mdx

@@ -0,0 +1,41 @@
+import Layout from "../../components/layout";
+
+export default Layout;
+
+# Colors
+
+There are three layers of color tokens in Base Web:
+
+### 1) Primitive colors
+
+These are the tokens that map directly to CSS hex values.
+
+Examples: `green100`, `yellow600`, `magenta200`
+
+### 2) Semantic colors
+
+These tokens play a fundamental semantic role in the Base design language. They map to layer 1 primitive color tokens.
+
+Examples: `contentPrimary`, `backgroundTeriary`, `borderWarning`
+
+### 3) Component colors
+
+These tokens are referenced inside Base Web styled components. They map both to primitive and semantic color tokens.
+
+Examples: `buttonPrimaryText`, `linkHover`
+
+### Deprecated colors
+
+The foundation color tokens are deprecated. These tokens include `primaryA`, `primaryB`, `accent`, `positive`, `negative`, `warning`, and all of their variations. They are a legacy holdover from the previous theme creation API, intended to provide a quick way to "skin" our standard light and dark themes. They will be removed in a future version of Base Web.
+
+## Using colors in your own components
+
+All of the color tokens can be accessed via your application's theme object. It's rarely necessary to use primitive color tokens directly in your application. In most cases, semantic color tokens are the best choice. They are named according to the role they play in the design system, making them easier to use and understand in the context of your application. This helps assure that your components will be accessible and consistent with the rest of the design system. They also adjust between light and dark themes automatically. See the [Semantic tokens](/guides/styling/#semantic-tokens) section of the style guide for examples.
+
+In some cases it may also make sense to use component color tokens. For example, if you create a custom button-like component, you can ensure consistency with other button components by using the collection of button-specific component color tokens that Base Web uses internally for styling its native button components.
+
+## Customizing colors
+
+To customize a specific instance of a component, use component overrides. For everything else, use the `overrides` argument of the [`createTheme`](./theming.mdx#createTheme) function.
+
+As with using color tokens, it is usually best to customize your theme by targeting semantic color tokens and remapping them onto Base Web's primitive color tokens.

documentation-site/pages/guides/styling.mdx

@@ -202,7 +202,7 @@ export default function StyledFancyLink(props) {
   return (
     <StyledLink
       $style={({ $theme }) => ({
-        color: $theme.colors.primary,
+        color: $theme.colors.contentPrimary,
       })}
       {...props}
     />
@@ -219,7 +219,7 @@ import { withStyle } from "baseui";
 import { StyledLink } from "./link";
 
 export const StyledFancyLink = withStyle(StyledLink, ({ $theme }) => ({
-  color: $theme.colors.primary,
+  color: $theme.colors.contentPrimary,
 }));
 ```
 
@@ -359,37 +359,6 @@ There are three main techniques for styling Base Web components: the theme, `wit
 
 The [theming guide](/guides/theming) is your best resource for understanding the nuances of theming Base Web components. Theming is the first strategy we would recommend trying out when styling Base Web components. You can modify spacing, border radii, colors, typography scales- a whole slew of systemic theme tokens which will change the look of Base Web.
 
-```js
-import { createLightTheme } from "baseui";
-const primitives = {
-  accent: "#F127E4", // hot pink
-  accent50: "#FDEDFC",
-  accent100: "#FCD3F9",
-  accent200: "#F89FF3",
-  accent300: "#F45AEA",
-  accent400: "#F127E4",
-  accent500: "#B71DAD",
-  accent600: "#901788",
-  accent700: "#600F5B",
-};
-
-const overrides = {
-  colors: {
-    buttonSecondaryFill: primitives.accent100,
-    buttonSecondaryText: primitives.accent,
-    buttonSecondaryHover: primitives.accent200,
-    buttonSecondaryActive: primitives.accent300,
-    buttonSecondarySelectedFill: primitives.accent200,
-    buttonSecondarySelectedText: primitives.accent,
-    buttonSecondarySpinnerForeground: primitives.accent700,
-    buttonSecondarySpinnerBackground: primitives.accent300,
-  },
-};
-
-export const lightTheme = createLightTheme(primitives, overrides);
-export const darkTheme = createDarkTheme(primitives, overrides);
-```
-
 We think you can get pretty far with just the theming layer alone. When it isn’t enough there are a few more techniques available to you.
 
 ### withStyle
@@ -401,7 +370,7 @@ import { withStyle } from "baseui";
 import { StyledLink } from "baseui/link";
 
 export const MyStyledLink = withStyle(StyledLink, ({ $theme }) => ({
-  borderBottom: `solid 2px ${theme.colors.primary}`,
+  borderBottom: `solid 2px ${theme.colors.contentPrimary}`,
 }));
 ```