Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for element tokens #4633

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Add docs for element tokens #4633

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions aries-site/src/data/structures/tokens.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: () => <Text size="large">hpe.element.medium.paddingY</Text>,
},
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',
Expand Down
109 changes: 109 additions & 0 deletions aries-site/src/examples/tokens/element/ElementToken.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 (
<Box
background={
token === 'minHeight' || token === 'width' || token === 'height'
? { color: 'brand', opacity: 'weak' }
: undefined
}
border={{
color: token === 'borderWidth' ? 'brand' : 'border',
style: token === 'borderWidth' ? 'dashed' : 'solid',
width: components.hpe.element.medium.borderWidth,
}}
round="xsmall"
overflow="hidden"
direction="row"
alignSelf="start"
width={
token === 'width' || token === 'height'
? components.hpe.element.medium.width
: undefined
}
height={
token === 'width' || token === 'height'
? components.hpe.element.medium.width
: undefined
}
>
{token !== 'width' && token !== 'height' ? (
<>
<Box
width={paddingX}
background={token.includes('paddingX') ? 'brand' : undefined}
/>
<Box flex>
<Box
height={components.hpe.element.medium.paddingY}
background={token === 'paddingY' ? 'brand' : undefined}
/>
<Box direction="row" align="center">
<Box
background={
token === 'icon.size'
? { color: 'brand', opacity: 'weak' }
: undefined
}
border={
token === 'icon.size'
? { color: 'brand', style: 'dashed' }
: undefined
}
>
{token === 'textToElementX' ? <CheckBox pad="none" /> : <Add />}
</Box>
<Box
width={
token === 'textToElementX'
? components.hpe.element.medium.textToElementX
: components.hpe.element.medium.textToIconX
}
background={token.includes('textTo') ? 'brand' : undefined}
height={components.hpe.element.medium.lineHeight}
/>
<Box
background={
token === 'lineHeight'
? { color: 'brand', opacity: 'weak' }
: undefined
}
border={
token === 'lineHeight'
? { color: 'brand', style: 'dashed' }
: undefined
}
>
<Text>Hello world</Text>
</Box>
</Box>
<Box
height={components.hpe.element.medium.paddingY}
background={token === 'paddingY' ? 'brand' : undefined}
/>
</Box>
<Box
width={paddingX}
background={token.includes('paddingX') ? 'brand' : undefined}
/>
</>
) : undefined}
</Box>
);
};

ElementToken.propTypes = {
token: PropTypes.string.isRequired,
};
1 change: 1 addition & 0 deletions aries-site/src/examples/tokens/element/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export * from './ElementToken';
1 change: 1 addition & 0 deletions aries-site/src/examples/tokens/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
export * from './BetaNotification';
export * from './TokenHighlight';
export * from './TokenTypes';
export * from './element';
48 changes: 48 additions & 0 deletions aries-site/src/pages/design-tokens/element.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. | <ElementToken token="ElementToken" /> |
| **element.[size].width** | Use for fixed size components like avatar, spinner, etc. | <ElementToken token="width" /> |
| **element.[size].height** | Use for fixed size components like avatar, spinner, etc. | <ElementToken token="height" /> |
| **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" /> |
| **element.[size].paddingX.default** | Use for standard horizontal padding. | <ElementToken token="paddingX.default" /> |
| **element.[size].paddingX.wide** | Use for components that are fully rounded or need more horizontal affordance. | <ElementToken token="paddingX.wide" /> |
| **element.[size].paddingY** | -- | <ElementToken token="paddingY" /> |
| **element.[size].textToIconX** | Use for spacing between text and icon. | <ElementToken token="textToIconX" /> |
| **element.[size].textToElementX** | Use for spacing between text and an internal control like a checkbox. | <ElementToken token="textToElementX" /> |
| **element.[size].borderWidth** | -- | <ElementToken token="borderWidth" /> |
| **element.[size].lineHeight** | -- | <ElementToken token="lineHeight" /> |
| **element.[size].fontSize** | -- | <ElementToken token="fontSize" /> |
| **element.[size].fontWeight** | -- | <ElementToken token="fontWeight" /> |
| **element.[size].icon.size** | Applies to width and height of icon. | <ElementToken token="icon.size" /> |
Loading