diff --git a/aries-site/src/data/structures/tokens.js b/aries-site/src/data/structures/tokens.js
index bf3f8270e..4fac5cb9f 100644
--- a/aries-site/src/data/structures/tokens.js
+++ b/aries-site/src/data/structures/tokens.js
@@ -38,6 +38,24 @@ export const tokens = [
],
tags: [],
},
+ {
+ name: 'Element',
+ type: 'Getting started',
+ description:
+ 'Element tokens provide standardized sizing for core UI building blocks to ensure alignment in layouts.',
+ preview: {
+ component: () => hpe.element.medium.paddingY,
+ },
+ seoDescription:
+ 'Element tokens provide standardized sizing for core UI building blocks to ensure alignment in layouts.',
+ sections: [],
+ relatedContent: [
+ 'All design tokens',
+ 'Using design tokens in code',
+ 'Using design tokens in Figma',
+ ],
+ tags: [],
+ },
{
name: 'Using design tokens in code',
type: 'Building with tokens',
diff --git a/aries-site/src/examples/tokens/element/ElementToken.js b/aries-site/src/examples/tokens/element/ElementToken.js
new file mode 100644
index 000000000..dfe08b166
--- /dev/null
+++ b/aries-site/src/examples/tokens/element/ElementToken.js
@@ -0,0 +1,109 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { Box, CheckBox, Text } from 'grommet';
+import { components } from 'hpe-design-tokens';
+import { Add } from 'grommet-icons';
+
+export const ElementToken = ({ token }) => {
+ let paddingX = components.hpe.element.medium.paddingX.default;
+ if (token === 'paddingX.narrow') {
+ paddingX = components.hpe.element.medium.paddingX.narrow;
+ } else if (token === 'paddingX.wide') {
+ paddingX = components.hpe.element.medium.paddingX.wide;
+ }
+
+ return (
+
+ {token !== 'width' && token !== 'height' ? (
+ <>
+
+
+
+
+
+ {token === 'textToElementX' ? : }
+
+
+
+ Hello world
+
+
+
+
+
+
+ ) : undefined}
+
+ );
+};
+
+ElementToken.propTypes = {
+ token: PropTypes.string.isRequired,
+};
diff --git a/aries-site/src/examples/tokens/element/index.js b/aries-site/src/examples/tokens/element/index.js
new file mode 100644
index 000000000..d115b9d78
--- /dev/null
+++ b/aries-site/src/examples/tokens/element/index.js
@@ -0,0 +1 @@
+export * from './ElementToken';
diff --git a/aries-site/src/examples/tokens/index.js b/aries-site/src/examples/tokens/index.js
index 737e2671f..6ffcef5bd 100644
--- a/aries-site/src/examples/tokens/index.js
+++ b/aries-site/src/examples/tokens/index.js
@@ -1,3 +1,4 @@
export * from './BetaNotification';
export * from './TokenHighlight';
export * from './TokenTypes';
+export * from './element';
diff --git a/aries-site/src/pages/design-tokens/element.mdx b/aries-site/src/pages/design-tokens/element.mdx
new file mode 100644
index 000000000..8514f87cb
--- /dev/null
+++ b/aries-site/src/pages/design-tokens/element.mdx
@@ -0,0 +1,48 @@
+import { Notification } from 'grommet';
+import { BestPracticeGroup, Example } from '../../layouts';
+import { ElementToken } from '../../examples';
+
+In the HPE Design System, an "element" refers to a core UI building block.
+
+Elements can contain foundational items like text or icons, but "can't be broken down without ceasing to be functional." (source: [Atomic Design](https://atomicdesign.bradfrost.com/chapter-2/))
+
+To understand what element tokens apply to, consider various UI components as levels from most fundamental to most composed:
+
+| Level | Example components |
+| --------------------------- | --------------------------------------------------- |
+| **1. Typography, controls** | text, anchor, checkbox, radio button, toggle switch |
+| **2. Elements** | button, input, select, menu, table cells |
+| **3. Layout/compositional** | card, modal, toolbars |
+
+Many common "elements" (corresponding directly to native HTML tags or roles like button, input, select, etc.) have [component-specific design tokens](/design-tokens/how-to-read-design-tokens#component) published. These design tokens reference element tokens.
+
+## When to use
+
+Use element tokens when there is not a component-specific token available for an element. For example, a team may be designing a new component that is not offered by the design system. They can use element tokens to ensure that the new component aligns and adapts with the rest of the sizing system.
+
+Do not use element tokens for compositional components like cards, lists, or toolbars. Instead, use [semantic tokens](/design-tokens/overview#semantic-tokens).
+
+## Element sizes
+
+Element sizes are used to ensure consistent sizing and alignment across layouts. Sizes "xsmall"-"xlarge" are available.
+
+## Supported design tokens
+
+The following design tokens exist for each element size. Replace `[size]` with the desired size (e.g., `xsmall`, `small`, `medium`, `large`, `xlarge`).
+
+| Property | Notes | Example |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| **element.[size].minHeight** | Ensures elements achieve the desired minimum height even if internal content varies. | |
+| **element.[size].width** | Use for fixed size components like avatar, spinner, etc. | |
+| **element.[size].height** | Use for fixed size components like avatar, spinner, etc. | |
+| **element.[size].paddingX.narrow** | Use for components that should have equal horizontal and vertical padding. Often this applies to square components like icon-only buttons. | |
+| **element.[size].paddingX.default** | Use for standard horizontal padding. | |
+| **element.[size].paddingX.wide** | Use for components that are fully rounded or need more horizontal affordance. | |
+| **element.[size].paddingY** | -- | |
+| **element.[size].textToIconX** | Use for spacing between text and icon. | |
+| **element.[size].textToElementX** | Use for spacing between text and an internal control like a checkbox. | |
+| **element.[size].borderWidth** | -- | |
+| **element.[size].lineHeight** | -- | |
+| **element.[size].fontSize** | -- | |
+| **element.[size].fontWeight** | -- | |
+| **element.[size].icon.size** | Applies to width and height of icon. | |