# Layout Helpers

Layout utilities provide low-level building blocks for spacing, positioning, alignment, and density.\
They are applied via utility classes prefixed with `tui-`. Layout helpers are low-level utilities intended for composition, not for replacing semantic structure or component-level styling.

Every helper resolves to the same primitives you can consume directly — `gap: var(--tui-spacing-md)` in your own CSS keeps the DOM clean and is always equivalent. See the [Utility Class Index](https://storybook-tangible-ui.pages.dev/docs/reference-utility-classes.md) and [Primitive Token Index](https://storybook-tangible-ui.pages.dev/docs/reference-primitive-tokens.md).

## Logical Properties

All layout helpers defined in the Tangible Design System use [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values) rather than explicit top, right, left, and bottom keywords, which helps to improve compatibility with writing directions aside from left-to-right. Left and right values are considered "inline", and top and bottom values are considered "block". These map as follows in LTR writing mode:

| Logical Property | Physical Property |
| - | - |
| `block` | `top` and `bottom` |
| `block-start` | `top` |
| `block-end` | `bottom` |
| `inline` | `left` and `right` |
| `inline-start` | `left` |
| `inline-end` | `right` |

It is usually appropriate to use logical properties rather than traditional physical properties, except in rare cases where positioning should not adapt to writing mode (ie. something should always be positioned in the top left of the screen, even in Arabic translations). Google has [published a set of guidelines](https://m2.material.io/design/usability/bidirectionality.html) for mirroring UIs for RTL
that provides helpful context about conventions.

If you need explicit positioning, it can be defined using a custom CSS rule rather than with helper classes.

## Position

| Class | Effect |
| - | - |
| `.tui-visually-hidden` | Positioned off-screen for screen-readers only, visually hidden. |
| `.tui-position-static` | `position: static` |
| `.tui-position-relative` | `position: relative` |
| `.tui-position-absolute` | `position: absolute` |
| `.tui-stretched-link::after` | Expands a child link to fill its container. |

## Margin

Shorthands for all sides (`margin`), block axis (y), and inline axis (x).

Examples:

- `.tui-margin-none` → `margin: 0`
- `.tui-margin-auto` → `margin: auto`
- `.tui-margin-md` → `margin: var(--tui-spacing-md)`
- `.tui-margin-inline-sm` → `margin-inline: var(--tui-spacing-sm)`

Supported sizes: `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `xxl`.

## Padding

Same structure as margin helpers.

Examples:

- `.tui-padding-none`
- `.tui-padding-md`
- `.tui-padding-inline-lg`

## Containers

Use container queries with consistent naming. The default name for containers defined with this helper is `tuiContainer`, but it can be updated by changing the value of the variable `--tui-container-name`. Keep in mind that styling within container query at-rules can't target the defined container. [Learn more about container queries here](https://developer.mozilla.org/en-US/docs/Web/CSS/@container)

| Class | Container type | Usage |
| - | - | - |
| `.tui-container` | `inline-size` | Width-based queries. |
| `.tui-container--size` | `size` | Width + height queries. |

```css
@container (min-width: 40rem) {
  .card { flex-direction: row; }
}
```

## Flex

Use `.tui-flex` and related helpers to create flex-mode layouts. Lists with `.tui-flex`, `.tui-inline-flex` or `.tui-stack` applied will have their list styles cleared automatically.

| Class | Effect |
| - | - |
| `.tui-flex` | `display: flex` with gap support |
| `.tui-flex.is-wrap` | Wrap children |
| `.tui-flex.is-nowrap` | Prevent wrapping |
| `.tui-inline-flex` | Inline flex |
| `.tui-stack` | Column flex stack with vertical gaps |

Alignment helpers:

- `.is-align-start`, `.is-align-center`, `.is-align-end`, `.is-align-stretch`
- `.is-justify-start`, `.is-justify-center`, `.is-justify-end`, `.is-justify-between`, `.is-justify-around`, `.is-justify-evenly`
- `.is-align-self-*` variants for individual items

## Grid

| Class | Effect |
| - | - |
| `.tui-grid` | `display: grid` with gaps |
| `.tui-grid--cols-N` | N fixed columns (1–12) |
| `.tui-grid--auto` | Auto-fit grid with min column size (default 12rem) |
| `.tui-col-span-N` | Grid item span |
| `.tui-col-span-full` | Span all columns |

## Density (Gap)

Controls row/column gaps for both grid and flex containers, which default to gap size `md`. Density utilities update the `--tui-gap-inline` and `--tui-gap-block` custom properties.

Examples:

- `.is-density-none` → no gaps
- `.is-density-sm` → small gaps on both axes
- `.is-density-inline-lg` → only horizontal gaps
- `.is-density-block-md` → only vertical gaps

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/system-layout-helpers--docs