Skip to content

Commit 37f9f88

Browse files
tayseataysea
committed
Add docs for element tokens
1 parent 0a2accd commit 37f9f88

File tree

5 files changed

+177
-0
lines changed

5 files changed

+177
-0
lines changed

‎aries-site/src/data/structures/tokens.js

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,24 @@ export const tokens = [
3838
],
3939
tags: [],
4040
},
41+
{
42+
name: 'Element',
43+
type: 'Getting started',
44+
description:
45+
'Element tokens provide standardized sizing for core UI building blocks to ensure alignment in layouts.',
46+
preview: {
47+
component: () => <Text size="large">hpe.element.medium.paddingY</Text>,
48+
},
49+
seoDescription:
50+
'Element tokens provide standardized sizing for core UI building blocks to ensure alignment in layouts.',
51+
sections: [],
52+
relatedContent: [
53+
'All design tokens',
54+
'Using design tokens in code',
55+
'Using design tokens in Figma',
56+
],
57+
tags: [],
58+
},
4159
{
4260
name: 'Using design tokens in code',
4361
type: 'Building with tokens',

‎aries-site/src/examples/tokens/element/ElementToken.js

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
import React from 'react';
2+
import PropTypes from 'prop-types';
3+
import { Box, CheckBox, Text } from 'grommet';
4+
import { components } from 'hpe-design-tokens';
5+
import { Add } from 'grommet-icons';
6+
7+
export const ElementToken = ({ token }) => {
8+
let paddingX = components.hpe.element.medium.paddingX.default;
9+
if (token === 'paddingX.narrow') {
10+
paddingX = components.hpe.element.medium.paddingX.narrow;
11+
} else if (token === 'paddingX.wide') {
12+
paddingX = components.hpe.element.medium.paddingX.wide;
13+
}
14+
15+
return (
16+
<Box
17+
background={
18+
token === 'minHeight' || token === 'width' || token === 'height'
19+
? { color: 'brand', opacity: 'weak' }
20+
: undefined
21+
}
22+
border={{
23+
color: token === 'borderWidth' ? 'brand' : 'border',
24+
style: token === 'borderWidth' ? 'dashed' : 'solid',
25+
width: components.hpe.element.medium.borderWidth,
26+
}}
27+
round="xsmall"
28+
overflow="hidden"
29+
direction="row"
30+
alignSelf="start"
31+
width={
32+
token === 'width' || token === 'height'
33+
? components.hpe.element.medium.width
34+
: undefined
35+
}
36+
height={
37+
token === 'width' || token === 'height'
38+
? components.hpe.element.medium.width
39+
: undefined
40+
}
41+
>
42+
{token !== 'width' && token !== 'height' ? (
43+
<>
44+
<Box
45+
width={paddingX}
46+
background={token.includes('paddingX') ? 'brand' : undefined}
47+
/>
48+
<Box flex>
49+
<Box
50+
height={components.hpe.element.medium.paddingY}
51+
background={token === 'paddingY' ? 'brand' : undefined}
52+
/>
53+
<Box direction="row" align="center">
54+
<Box
55+
background={
56+
token === 'icon.size'
57+
? { color: 'brand', opacity: 'weak' }
58+
: undefined
59+
}
60+
border={
61+
token === 'icon.size'
62+
? { color: 'brand', style: 'dashed' }
63+
: undefined
64+
}
65+
>
66+
{token === 'textToElementX' ? <CheckBox pad="none" /> : <Add />}
67+
</Box>
68+
<Box
69+
width={
70+
token === 'textToElementX'
71+
? components.hpe.element.medium.textToElementX
72+
: components.hpe.element.medium.textToIconX
73+
}
74+
background={token.includes('textTo') ? 'brand' : undefined}
75+
height={components.hpe.element.medium.lineHeight}
76+
/>
77+
<Box
78+
background={
79+
token === 'lineHeight'
80+
? { color: 'brand', opacity: 'weak' }
81+
: undefined
82+
}
83+
border={
84+
token === 'lineHeight'
85+
? { color: 'brand', style: 'dashed' }
86+
: undefined
87+
}
88+
>
89+
<Text>Hello world</Text>
90+
</Box>
91+
</Box>
92+
<Box
93+
height={components.hpe.element.medium.paddingY}
94+
background={token === 'paddingY' ? 'brand' : undefined}
95+
/>
96+
</Box>
97+
<Box
98+
width={paddingX}
99+
background={token.includes('paddingX') ? 'brand' : undefined}
100+
/>
101+
</>
102+
) : undefined}
103+
</Box>
104+
);
105+
};
106+
107+
ElementToken.propTypes = {
108+
token: PropTypes.string.isRequired,
109+
};

‎aries-site/src/examples/tokens/element/index.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export * from './ElementToken';

‎aries-site/src/examples/tokens/index.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
export * from './BetaNotification';
22
export * from './TokenHighlight';
33
export * from './TokenTypes';
4+
export * from './element';

‎aries-site/src/pages/design-tokens/element.mdx

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import { Notification } from 'grommet';
2+
import { BestPracticeGroup, Example } from '../../layouts';
3+
import { ElementToken } from '../../examples';
4+
5+
In the HPE Design System, an "element" refers to a core UI building block.
6+
7+
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/))
8+
9+
To understand what element tokens apply to, consider various UI components as levels from most fundamental to most composed:
10+
11+
| Level | Example components |
12+
| --------------------------- | --------------------------------------------------- |
13+
| **1. Typography, controls** | text, anchor, checkbox, radio button, toggle switch |
14+
| **2. Elements** | button, input, select, menu, table cells |
15+
| **3. Layout/compositional** | card, modal, toolbars |
16+
17+
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.
18+
19+
## When to use
20+
21+
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.
22+
23+
Do not use element tokens for compositional components like cards, lists, or toolbars. Instead, use [semantic tokens](/design-tokens/overview#semantic-tokens).
24+
25+
## Element sizes
26+
27+
Element sizes are used to ensure consistent sizing and alignment across layouts. Sizes "xsmall"-"xlarge" are available.
28+
29+
## Supported design tokens
30+
31+
The following design tokens exist for each element size. Replace `[size]` with the desired size (e.g., `xsmall`, `small`, `medium`, `large`, `xlarge`).
32+
33+
| Property | Notes | Example |
34+
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
35+
| **element.[size].minHeight** | Ensures elements achieve the desired minimum height even if internal content varies. | <ElementToken token="ElementToken" /> |
36+
| **element.[size].width** | Use for fixed size components like avatar, spinner, etc. | <ElementToken token="width" /> |
37+
| **element.[size].height** | Use for fixed size components like avatar, spinner, etc. | <ElementToken token="height" /> |
38+
| **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. | <ElementToken token="paddingX.narrow" /> |
39+
| **element.[size].paddingX.default** | Use for standard horizontal padding. | <ElementToken token="paddingX.default" /> |
40+
| **element.[size].paddingX.wide** | Use for components that are fully rounded or need more horizontal affordance. | <ElementToken token="paddingX.wide" /> |
41+
| **element.[size].paddingY** | -- | <ElementToken token="paddingY" /> |
42+
| **element.[size].textToIconX** | Use for spacing between text and icon. | <ElementToken token="textToIconX" /> |
43+
| **element.[size].textToElementX** | Use for spacing between text and an internal control like a checkbox. | <ElementToken token="textToElementX" /> |
44+
| **element.[size].borderWidth** | -- | <ElementToken token="borderWidth" /> |
45+
| **element.[size].lineHeight** | -- | <ElementToken token="lineHeight" /> |
46+
| **element.[size].fontSize** | -- | <ElementToken token="fontSize" /> |
47+
| **element.[size].fontWeight** | -- | <ElementToken token="fontWeight" /> |
48+
| **element.[size].icon.size** | Applies to width and height of icon. | <ElementToken token="icon.size" /> |

0 commit comments

Comments
 (0)