docs: clean up contribution doc.s

.storybook/components/Docs/Guidelines/CodeGuidelines.stories.mdx

@@ -222,36 +222,18 @@ For example:
 
 /**
  * Full width button.
- *
- * Class is doubled to increase specificity.
  */
-.button--full-width.button--full-width {
+.button--full-width {
   background: red;
   /* Pushes the button away from the other content because it lives in a flexbox container */
   margin-right: auto;
   width: 100%;
-  /* I know this a weird magic number, but [succinct-but-clear explanation] */
-  height: 37px;
 }
 ```
 
 Not all CSS declarations warrant a comment, but non-obvious declarations (like context-specific styles, magic numbers, or styles dependent on other selector styles) should be accompanied by a comment.
 
-### Other CSS Rules
-
-- EDS generally arranges CSS properties in the following manner (although more as a guideline than a strictly-enforced convention):
-
-```css
-.element {
-  [mixin includes, including typography]
-  [positioning]
-  [box model]
-  [color]
-  [transition]
-}
-```
-
-- Media queries should live inside each class name. This makes it easier for a developer to focus on a class name, rather than finding confusion with class names written twice in a file and getting lost.
+Also, media queries should live inside each class name. This makes it easier for a developer to focus on a class name, rather than finding confusion with class names written twice in a file and getting lost.
 
 Instead of:
 
@@ -286,14 +268,14 @@ Instead of:
 ```
 import { EdsThemeColorUtilitySuccessForeground } from 'src/tokens-dist/ts/colors';
 
-<Icon color={EdsThemeColorUtilitySuccessForeground} />;
+<SomeComponent color={EdsThemeColorUtilitySuccessForeground} />;
 ```
 
 Use:
 
 ```css
 .banner__icon {
-  fill: var(--eds-theme-color-utility-success-foreground);
+  fill: var(--eds-theme-color-utility-favorable);
 }
 ```
 
@@ -570,20 +552,18 @@ EDS adheres to the following API naming conventions:
 
 The default option should be the one most commonly used in order to reduce friction for developers using the components.
 
-- `variant` should be used for primary _stylistic_ variations of a component, such as (e.g. `<Card variant="bordered">` or `<Button variant="secondary">`). `variant` should be used if there is primarily one variable used to manipulate the component style.
-- `size` should be used for adjusting size attributes (e.g. `<Button variant="secondary" size="sm">` or `<Button size="md"`>). Use abbreviations for sizes (ex: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`).
-- `behavior` should be used for functional variations of a pattern, such as `<Banner behavior="dismissable">`. Additional non-exclusive behaviors should be handled using boolean props prefixed with `is` (e.g. `isSticky` and `isDismissable`).
-- `orientation` should be used for controlling the layout or orientation of a component (e.g. `<ButtonGroup orientation="stacked">`)
-- `disabled` boolean should be used to control the interactivity of a component (e.g. `<Button disabled />`)
-- `verticalAlign` should be used for vertically aligning content, and should include `top`, `middle`, `bottom` if needed.
+- `variant` should be used for primary _stylistic_ variations of a component, such as (e.g. `<Card variant="bordered">`). `variant` should be used if there is primarily one variable used to manipulate the component style.
+- `size` should be used for adjusting size attributes (e.g. `<Button rank="secondary" size="sm">` or `<Button size="md"`>). Use abbreviations for sizes (ex: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`).
+- `isDisabled` boolean should be used to control the interactivity of a component (e.g. `<Button isDisabled />`)
 
 ### Text, Labels, Titles, and Children
 
 - Default to `text` for short strings of text, such as `<BreadCrumbsItem text="My Courses">` or `<Badge text="Overdue" />`.
-- For headings, default to `title`, such as `<PageHeader title="My Page Title">`.
-- Default to `description` for text that serves as a descriptor, such as `<PageHeader title="Project name" description="Brief overview of the project..." />`
-- For form-related components, use the semantic `label` or `legend` (e.g. `<TextField label="first name" />` and `<Fieldset.Legend text="Grade level">`).
+- For headings, default to `title`, such as `<Card.Header title="My Page Title" />`.
+- Default to `subTitle` for text that serves as a descriptor, such as `<Card.Header title="Project name" subTitle="Brief overview of the project..." />`
+- For form-related components, use the semantic `label` or `legend` (e.g. `<InputField label="first name" />` and `<Fieldset.Legend text="Grade level">`).
 - `children` can be used for components that only have one main block of content being passed in (so there will be no confusion with other content props) and when it's safe for that content to be a `ReactNode`. (If it's important for the content to only come in the form of a string, restrict the type to `string`).
+- instead of styling text using internal typography tokens, use `Text` and `Heading` components with the appropriate `preset` to match design.
 
 ### Tag name
 

.storybook/components/Docs/Guidelines/Components.stories.mdx

@@ -28,11 +28,11 @@ From there, call EDS components in your React application and pass in the desire
 
 ```jsx
 <Button
-  variant="primary"
+  rank="primary"
   onClick={...}
 >
   Submit
-  <Icon name="chevron-right" purpose="decorative" />
+  <Icon name="arrow-right" purpose="decorative" />
 </Button>
 ```
 

.storybook/components/Docs/Guidelines/Icons.stories.mdx

@@ -12,11 +12,11 @@ EDS provides utilitarian UI icons (e.g. magnifying glass, menu, triangles, caret
 
 ### Adding a new icon
 
-1. Export SVG icon asset(s) from Figma
-2. If necessary, remove the `fill` attribute on the `<path>` in the exported SVG file(s). In the very rare case that an icon needs colors defined in the icon (like the `status-` icons), only use tier 2 or tier 3 CSS variables for the color.
-3. In a new feature branch, locate `src/icons/spritemap` and add new icon contents (everything but the `<svg>` element) to the object.
-4. In Storybook, view the "Icon Grid" component to see the new component added to the available list of icons, which is now ready to use in EDS components.
-5. Submit PR to [edu-design-system](https://github.com/chanzuckerberg/edu-design-system)
+- Retrieve the icons from a design partner (e.g., from Figma, or from file sharing service like Google drive)
+- If necessary, remove the `fill` attribute on the `<path>` in the exported SVG file(s). In the very rare case that an icon needs colors defined in the icon (like the `status-` icons), only use tier 2 or tier 3 CSS variables for the color.
+- In a new feature branch, locate `src/icons/spritemap` and add new icon contents (everything but the `<svg>` element) to the object.
+- In Storybook, view the "Icon Grid" component to see the new component added to the available list of icons, which is now ready to use in EDS components.
+- Submit PR to [edu-design-system](https://github.com/chanzuckerberg/edu-design-system)
 
 For more information on contributing to EDS, please review our [contribution guidelines][contributing].
 

.storybook/components/Docs/Guidelines/Theming.stories.mdx

@@ -127,7 +127,7 @@ Once run, you will have a set of theme files written to the configured `dest` pa
 
 To use, add this file to your core app root file **after** where the imported EDS's `@chanzuckerberg/eds/index.css` file is inserted.
 
-### eds-import-from-Figma
+### eds-import-from-figma
 
 Command to run: `npx eds-import-from-figma`
 

.storybook/components/Docs/Guidelines/Tokens.stories.mdx

@@ -13,15 +13,13 @@ EDS is a [themeable design system](https://bradfrost.com/blog/post/creating-them
   - [Borders](#tier-1-borders)
   - [Breakpoints](#tier-1-breakpoints)
   - [Colors](#tier-1-colors)
-  - [Layout](#tier-1-layout)
   - [Shadows](#tier-1-shadows)
   - [Size](#tier-1-size)
   - [Typography](#tier-1-typography)
   - [Z-index](#tier-1-z-index)
 - [Tier 2 Usage Tokens](#tier-2-usage-tokens)
   - [Border](#tier-2-borders)
   - [Color](#tier-2-colors)
-  - [Form](#tier-2-forms)
 - [Tier 3 Component Tokens](#tier-3-component-tokens)
 
 ## Style Dictionary
@@ -53,7 +51,7 @@ EDS's token architecture and nomenclature is as follows:
 
 ## Tier 1 tokens
 
-Tier 1 tokens define the brand's design values. They can be thought of as a brand style guide converted into variables. Tier1 token values should not imply any UI usage, and should not be used directly by components. Instead, Tier 1 values should be mapped to Tier 2 values.
+[Tier 1 tokens](/?path=/docs/design-tokens-tier-1-definitions--docs) define the brand's design values. They can be thought of as a brand style guide converted into variables. Tier1 token values should not imply any UI usage, and should not be used directly by components. Instead, Tier 1 values should be mapped to Tier 2 values.
 
 ### Animation <a name="tier-1-animation"></a>
 
@@ -68,48 +66,38 @@ Tier 1 tokens define the brand's design values. They can be thought of as a bran
 
 ### Breakpoints <a name="tier-1-breakpoints"></a>
 
-- `bp-` for breakpoint. Typically default to t-shirt sizes (e.g. `bp-sm`, `bp-md`, etc). EDS[deliberately avoids](https://bradfrost.com/blog/post/7-habits-of-highly-effective-media-queries/) using "mobile" and "tablet" and "desktop" as values, despite it being a common nomenclature. 
+- `bp-` for breakpoint. Typically default to t-shirt sizes (e.g. `bp-sm`, `bp-md`, etc). EDS [deliberately avoids](https://bradfrost.com/blog/post/7-habits-of-highly-effective-media-queries/) using "mobile" and "tablet" and "desktop" as values, despite it being a common nomenclature. 
 
 **NOTE**: These are currently defined directly as SCSS variables due to lack of support at the moment for CSS custom property media queries.
 
 ### Colors <a name="tier-1-colors"></a>
 
-- `color-brand-` for brand-specific values (e.g. `color-brand-starbucks-green` or `color-brand-coca-cola-red`)
-- `color-neutral-` for black, white, and grayscale (or similar) values (e.g. `color-neutral-white`, or `color-neutral-50`). EDS defaults to the [percentage gray](https://medium.com/eightshapes-llc/color-in-design-systems-a1c80f65fa3) instead of using values like "gray-light" and "gray-dark". `color-neutral-90` is closer to black and `color-neutral-02` is a very light gray.
-- `color-transparent-` for semi-transparent values often used for backdrops and overlays (e.g. for a modal overlay)
-- `color-other-` for any other useful colors, especially for utility colors like info, warning, error, success, and info. Note that the semantic value for these other colors are assigned at the Tier 2 token level.
-
-### Layout <a name="tier-1-layout"></a>
-
-- `l-max-width` caps the width of a layout container so it doesn't span the full width of the viewport.
-- `l-linelength-width` for containing passages of text to a comfortable character length
+Tier 1 colors define ranges of colors across various hues. Numbers indicate various saturations, and can be used as a guide for choosing accessible combinations.
 
 ### Shadows <a name="tier-1-shadows"></a>
 
 - `box-shadow-` for box shadow definitions. Default to t-shirt sizes (e.g. `box-shadow-lg`).
 
 ### Size <a name="tier-1-size"></a>
 
-- `size-base-unit-` describes the base unit which most size-based units (`margin`, `padding`, `width`, `height`, etc) will use. We set this to `0.5rem` (which is equivalent to `8px`) in order to adhere to an [8-point grid](https://medium.com/built-to-adapt/intro-to-the-8-point-grid-system-d2573cde8632).
+We use size tokens, based on an 8-pixel grid size. Variables are prefixed with `--eds-size` and have units corresponding to 8 pixels each. We also provide tokens for some partial sizes (e.g,. 1.5 grid units, or 12 pixels).
 
 ### Typography <a name="tier-1-typography"></a>
 
 - `font-family-` for font family definitions. EDS defaults to "primary" and "secondary" for font-family definitions.
-- `font-size-` for font size definitions. Font sizes are based on pixel sizes and use `rem` (e.g., `font-size-16` = `1rem`)
 - `font-weight-` for the different weights. EDS defaults to "light", "medium", and "bold".
 - `letter-spacing` for the spacing between text characters. This uses t-shirt sizes.
-- `line-height-` for line height definitions. These are unitless relative values. Default to t-shirt sizes (e.g. `line-height-lg: 1.5` )
 
 Individual presets and typography tokens are defined as a set of values to apply to the [CSS Font property](https://developer.mozilla.org/en-US/docs/Web/CSS/font).
 See [Typography](/story/documentation-guidelines-typography--page) for more information.
 
 ### Z-index <a name="tier-1-z-index"></a>
 
-- `z-index-` controls an item's position in the stacking order. For now, EDS defaults to values that map to "top", "bottom", and some set z-index values (e.g., 0, 100, 200, 300, 400, 500).
+- `z-index-` controls an item's position in the stacking order. For now, EDS defaults to values that map to "top", "bottom".
 
 ## Tier 2 usage tokens
 
-Tier 2 tokens define a semantic UI layer. Tier 2 values use Tier 1 token values, mapping them to specific UI applications, which are in then used by individual component styles.
+[Tier 2 tokens](/?path=/docs/design-tokens-tier-2-usage--docs) define a semantic UI layer. Tier 2 values use Tier 1 token values, mapping them to specific UI applications, which are in then used by individual component styles.
 
 All Tier 2 tokens begin with the prefix `eds-theme-`. For specific documentation around specific theme tokens, please refer to the token page in Storybook, which articulate the role of each theme token.
 
@@ -125,29 +113,8 @@ Each token in this group is prefixed by `--eds-theme-color` and has certain suff
 
 For more information, [refer to Storybook](/story/design-tokens-tier-2-usage--colors) for the existing tokens and their naming.
 
-### Forms <a name="tier-2-forms"></a>
-
-Defines the border width, radius, and color properties for form controls. These values are all mapped to other Tier 2 values and are considered optional in case remapping is required.
-
-- `form-border-width` defines the default border width for any form element
-- `form-border-radius` defines the default border radius used on any form element's border
-
 ## Tier 3 Component Tokens <a name="tier-3-component-tokens"></a>
 
-Tier 3 component variables represent each component's specific values.
-
-Naming for tier-3 tokens will use the following prefix:
-
-```css
---eds-theme-[property]-[component-name]
-```
-
-With the rest matching a corresponding use for the given component. For example, if a modal is to have a specific header background color, the token to use is:
-
-```css
---eds-theme-color-modal-brand-header-background
-```
-
-The suffix here is arbitrary, but uses similar naming to tier two tokens. When possible, any new tier 3 tokens should be a more specifically named tier 2 token, to keep the naming consistent.
+[Tier 3 component tokens](/?path=/docs/design-tokens-tier-3-component--docs) represent each component's specific values.
 
-See the current set of tier 3 tokens [in storybook](/story/design-tokens-tier-3-component--colors).
+See the current set of tier 3 tokens [in storybook](/story/design-tokens-tier-3-component--colors). Note: many of these are deprecated and will be removed in a future release of EDS.

src/components/Icon/Icon.stories.tsx

@@ -2,7 +2,7 @@ import type { StoryObj, Meta } from '@storybook/react';
 import kebabCase from 'lodash/kebabCase';
 import React from 'react';
 import { Icon, type IconProps } from './Icon';
-import icons, { type IconName } from '../../icons/spritemap-v2';
+import icons, { type IconName } from '../../icons/spritemap';
 import * as ColorTokens from '../../tokens-dist/ts/colors';
 import Text from '../Text';
 

src/components/Icon/Icon.tsx

@@ -1,10 +1,10 @@
 import clsx from 'clsx';
 import type { ReactNode, CSSProperties } from 'react';
 import React from 'react';
-import icons, { type IconName } from '../../icons/spritemap-v2';
+import icons, { type IconName } from '../../icons/spritemap';
 import styles from './Icon.module.css';
 
-export type { IconName } from '../../icons/spritemap-v2';
+export type { IconName } from '../../icons/spritemap';
 
 // TODO: export union utility type of "Extract<IconName, T> | (renderProps) => ReactNode" when updating IconName usages
 

src/components/Menu/Menu.stories.tsx

@@ -5,7 +5,7 @@ import React from 'react';
 import { Menu } from './Menu';
 import type { MenuProps } from './Menu';
 import icons from '../../icons/spritemap';
-import type { IconName } from '../../icons/spritemap-v2';
+import type { IconName } from '../../icons/spritemap';
 import { Avatar } from '../Avatar/Avatar';
 
 import { Icon } from '../Icon/Icon';