diff --git a/storybook/stories/foundations/design-language/radius.mdx b/storybook/stories/foundations/design-language/radius.mdx new file mode 100644 index 00000000000000..515ee76badbf5f --- /dev/null +++ b/storybook/stories/foundations/design-language/radius.mdx @@ -0,0 +1,46 @@ +import { Meta, Typeset } from '@storybook/addon-docs/blocks'; +import { linkTo, hrefTo } from '@storybook/addon-links'; +import radius from './static/radius.svg'; +import radiusDo from './static/radius-do.svg'; +import radiusDont from './static/radius-dont.svg'; + + + +# Radius + +Radius + +The radius scale is designed to provide a consistent, elegant appearance across nested elements. The defined values help maintain visual harmony between smaller primitives and larger containers, ensuring a cohesive user experience. + +## Scale +The scale includes the following steps: + +* `radius-x-small`: Applied to the smallest elements, such as buttons inside inputs or similar small primitives. This ensures subtle rounding without distracting from the core design. +* `radius-small`: The most commonly used radius value, applied to many primitives like buttons, inputs, and other standalone controls. It provides a moderate rounding that feels balanced and polished. +* `radius-medium`: Used for medium-sized containers like dropdown menus, popovers, and other mid-level components. This value is slightly more pronounced, giving these elements a soft but noticeable edge. +* `radius-large`: Reserved for larger containers such as cards and modals. The larger radius ensures that these elements have a smooth, elegant appearance that enhances their prominence on the page. +* `radius-full`: Applies a `border-radius` of `9999px`, this value creates a highly rounded appearance, often used on pill-shaped buttons or other components where extreme rounding is desired but full circularity is not necessary. +* `radius-round`: This value applies a `border-radius` of `100%`, making elements fully circular. It's typically used for circular avatars or buttons where complete rounding is required. + +These steps are defined as tokens. To view the values and understand how to use them please view the [Tokens section](?path=/docs/tokens-radius--page). + +## Usage Guidelines +* Consistency: To maintain visual cohesion, adhere to the radius scale when styling elements. Avoid custom radius values unless there is a specific need. +* Nested Elements: When combining elements of different sizes (e.g., buttons within inputs or cards within modals), ensure that smaller nested elements use the appropriate radius value for their size. +* Accessibility: Larger radius values can create a more approachable and friendly appearance, especially for larger components like cards and modals that demand more attention from users. + + + + + + + +
✅ Do🚫 Don't
+Radius do +* Scale application of radius with element or container size. +* Use `radius-round` for circles and `radius-full` for pills. + +Radius don't +* Don't nest larger radii inside smaller radii. +* Don't apply the same radius value to container and immediate descendent. +
diff --git a/storybook/stories/foundations/design-language/static/radius-do.svg b/storybook/stories/foundations/design-language/static/radius-do.svg new file mode 100644 index 00000000000000..39084d973eac39 --- /dev/null +++ b/storybook/stories/foundations/design-language/static/radius-do.svg @@ -0,0 +1,58 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/storybook/stories/foundations/design-language/static/radius-dont.svg b/storybook/stories/foundations/design-language/static/radius-dont.svg new file mode 100644 index 00000000000000..fa0ee8c4de4507 --- /dev/null +++ b/storybook/stories/foundations/design-language/static/radius-dont.svg @@ -0,0 +1,58 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/storybook/stories/foundations/design-language/static/radius.svg b/storybook/stories/foundations/design-language/static/radius.svg new file mode 100644 index 00000000000000..5fd4705121797e --- /dev/null +++ b/storybook/stories/foundations/design-language/static/radius.svg @@ -0,0 +1,62 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/storybook/stories/tokens/components.tsx b/storybook/stories/tokens/components.tsx new file mode 100644 index 00000000000000..86589f350e7e31 --- /dev/null +++ b/storybook/stories/tokens/components.tsx @@ -0,0 +1,54 @@ +/** + * External dependencies + */ +// eslint-disable-next-line @typescript-eslint/no-restricted-imports +import React from 'react'; + +export const RadiusTable = ( { tokens } ) => { + return ( + + + + + + + + + + { tokens.map( ( { name, valueShow, valueCode } ) => ( + + + + + + ) ) } + +
TokenValueExample
{ name } + + { valueShow } + + +
+
+ ); +}; diff --git a/storybook/stories/tokens/radius.mdx b/storybook/stories/tokens/radius.mdx new file mode 100644 index 00000000000000..73ce068d0eb065 --- /dev/null +++ b/storybook/stories/tokens/radius.mdx @@ -0,0 +1,112 @@ +import { Meta } from '@storybook/blocks'; +import { RadiusTable } from './components.tsx'; + + + +# Radius + +This document outlines the various tokens relating to radius in the WordPress design system. + +## Values + +Tokens can be used in different ways, but regardless of which method is used, each one is meant to be used as the value of the CSS `border-radius` property, and references the following values: + + + +## CSS tokens + +Radius tokens are defined as SASS variables: + +- `$radius-x-small` +- `$radius-small` +- `$radius-medium` +- `$radius-large` +- `$radius-full` +- `$radius-round` + +They can be used like so: + +```css +.radius-extra-small { + border-radius: $radius-x-small; +} +.radius-small { + border-radius: $radius-small; +} +.radius-medium { + border-radius: $radius-medium; +} +.radius-large { + border-radius: $radius-large; +} +.radius-full { + border-radius: $radius-full; +} +.radius-round { + border-radius: $radius-round; +} +``` + +## JS tokens + +When working in the `@wordpress/components` package, the radius tokens can also be consumed as JavaScript variables via the `CONFIG` object found in the `packages/components/src/utils/index.js` file: + +- `CONFIG.radiusXSmall` +- `CONFIG.radiusSmall` +- `CONFIG.radiusMedium` +- `CONFIG.radiusLarge` +- `CONFIG.radiusFull` +- `CONFIG.radiusRound` + +```js +// Note: the `CONFIG` object is only available within the `@wordpress/components` package. +import { CONFIG } from '../utils'; + +// Later in the code: +border-radius: ${ CONFIG.radiusXSmall }; +```