import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import LinkTo from '@storybook/addon-links/react';
import {
  Button,
  FilterIcon,
  Text,
  Link,
  Box,
  Head1,
  UnstyledButton,
  TertiaryButton,
} from '../../../src';

<Meta title="Design System/Layout/Overview" />

# Layout

Patchwork uses a layout manager based on a subset of concepts from flexbox. In practice, it should be familiar to people used to either flexbox or React Native's `<View>` component, but simplified.

A layout manager is there to help you avoid thinking about layout in terms of raw pixels. Instead, it allows you to define _relationships_ between components that _flow predictably_ as the screen is resized or the theme is changed.

A layout manager also allows things like spacing between items, breakpoints, and even grid parameters to be adjusted differently for our different themes.

## Concepts

Patchwork's layout manager revolves around five concepts:

### Stacks

As a rule, patchwork components that can contain children are responsible for deciding how they should be laid out. They accomplish this by implementing the **stacking mixin**, which is a set of props that control child element layout.

> Any component that implements the **stacking mixin** is called a `Stack`; a `Stack` defines the **layout relationship between a parent component and its children**.

A stack is essentially a subset of flexbox its features are <LinkTo kind="Design System/Layout/Stack">documented in detail here</LinkTo>.

### Stackees

Nearly all patchwork components implement the **stackee mixin**, which is a set of props that defines the **layout relationship between a component and its siblings**.

> Any component that exists inside a stack, and implements the **stackee mixin** is said to be a `Stackee`.

Stackees accept props that control their default size and how they should grow or shrink as their parent stack re-flows due to window size changes and other factors. These properties are <LinkTo kind="Design System/Layout/Stackee">documented in detail here</LinkTo>.

### Spacing

When laying patchwork components out next to each other, you will normally want some amount of margin or padding between them. Generally, our designs do not call for bespoke amounts of pixels but rather follow a [**space scale**](https://www.designsystems.com/space-grids-and-layouts/).

The space scale is a set of 7 fixed amounts of spacing, whose increments are dictated by the product theme (for example, increments of 10px). Advantages of using a space scales include

- UIs that feel predictable, professional, and consistent
- An organizational framework that frees developers and designers from worrying about pixels at the cost of higher level UX improvements.

Virtually all Patchwork components implement the **spacing** mixin, which allows you to apply elements of the space scale as margin or padding. These properties are <LinkTo kind="Design System/Layout/Spacing">documented in detail here</LinkTo>

### Page-Level Grid

At the top level, our designs are organized into a conceptual 12-column grid. <LinkTo kind="Design System/Layout/Grid">It is documented here</LinkTo>.

Note that the `Grid` components are not designed to be nested - they are page-level constructs only.

### Breakpoints

Patchwork defines four different "breakpoints", or places where a screen re-flows as the browser is resized. The layout needs of a small window or screen are different than those of a maximized window on a large monitor.

All of our layout-system properties accept per-breakpoint values, allowing the layout of a page to dramatically change from size to size without the need for duplicate JSX code.

## Takeaways

- Parent components define their layout relationships with their children using `stack` properties and padding.
- Sibling components define their layout relationships with each other using `stackee` properties and margin.
- The top level of a page is organized using the `Grid` and `GridItem` components.
- All of these constructs are responsive - you can selectively adjust them on a per-breakpoint basis.
