diff --git a/docs/contributor-docs/v10-upgrade-guide.md b/docs/contributor-docs/v10-upgrade-guide.md index 2f9590c4d2..085a462f05 100644 --- a/docs/contributor-docs/v10-upgrade-guide.md +++ b/docs/contributor-docs/v10-upgrade-guide.md @@ -1,7 +1,7 @@ --- title: Upgrade Guide for Version 10.0 category: Guides -order: 7 +order: 98 --- # Upgrade Guide for Version 10 diff --git a/docs/guides/layout-spacing.md b/docs/guides/layout-spacing.md new file mode 100644 index 0000000000..4a83f4df86 --- /dev/null +++ b/docs/guides/layout-spacing.md @@ -0,0 +1,96 @@ +--- +title: Layout Spacing +category: Guides +order: 8 +--- + +# Layout Spacing + +Our design system provides a set of spacing tokens for consistent layouts and components. Some tokens share values but should be used semantically. For instance, while both `tags` and `buttons` are 0.75rem, `buttons` should be used for spacing between buttons. + +## Tokens + +| Key | Value | Value in pixels | +| ----------------- | -------- | --------------- | +| space0 | 0rem | 0px | +| space2 | 0.125rem | 2px | +| space4 | 0.25rem | 4px | +| space8 | 0.5rem | 8px | +| space12 | 0.75rem | 12px | +| space16 | 1rem | 16px | +| space24 | 1.5rem | 24px | +| space36 | 2.25rem | 36px | +| space48 | 3rem | 48px | +| space60 | 3.75rem | 60px | +| sections | 2.25rem | 36px | +| sectionElements | 1.5em | 24px | +| trayElements | 1.5em | 24px | +| modalElements | 1.5em | 24px | +| moduleElements | 1em | 16px | +| paddingCardLarge | 1.5rem | 24px | +| paddingCardMedium | 1rem | 16px | +| paddingCardSmall | 0.75rem | 12px | +| selects | 1rem | 16px | +| textAreas | 1rem | 16px | +| inputFields | 1rem | 16px | +| checkboxes | 1rem | 16px | +| radios | 1rem | 16px | +| toggles | 1rem | 16px | +| buttons | 0.75rem | 12px | +| tags | 0.75rem | 12px | +| statusIndicators | 0.75rem | 12px | +| dataPoints | 0.75rem | 12px | + +## Applying Spacing + +There are three main ways to apply spacing in our component library: + +### 1. Using the `margin` Prop + +Most components in the library support a `margin` prop that works similarly to the CSS margin property. You can specify a single value or fine-tune individual margins (e.g., top, right, bottom, left). + +```ts +--- +type: example +--- +
+ + +
+``` + +### 2. Using a Container Component with the `gap` Prop + +For layouts, container components like `Flex` and `Grid` can be used with the gap prop to manage spacing between child elements. + +```ts +--- +type: example +--- + + + + +``` + +### 3. Importing Values from the Theme + +If you need to directly reference spacing values, you can import them from the theme. This approach is useful for applying spacing in inline styles or custom components. + +```ts +--- +type: code +--- +// import the canvas theme +import canvas from '@instructure/ui-themes' + +// use spacing values +
+ + +
+``` + +## Legacy tokens + +For compatibility reasons we still provide the legacy spacing tokens (`xxLarge`, `medium`, etc.) so old layouts don't break when updating InstUI but these tokens shouldn't be used when creating new layouts. diff --git a/packages/__examples__/.storybook/stories/MarginProp.tsx b/packages/__examples__/.storybook/stories/MarginProp.tsx new file mode 100644 index 0000000000..5575a95f67 --- /dev/null +++ b/packages/__examples__/.storybook/stories/MarginProp.tsx @@ -0,0 +1,60 @@ +/* + * The MIT License (MIT) + * + * Copyright (c) 2015 - present Instructure, Inc. + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +import React from 'react' +import { + Button, + ColorPicker, + TextInput, + TextArea, + NumberInput, + DateInput2 +} from '@instructure/ui' + +function MarginProp() { + return ( +
+ + +