<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# PageShell

The page column of a site: centred content with a side gutter that grows with the screen, and a wider column on big screens. Sizes are in `rem`, so the larger root text size that `ouro-base` sets on big screens widens the column with it, and a huge display is not a thin strip of text in a sea of margin.

## Install

Once per app, with Tailwind CSS v4 and an `@/*` path alias (skip `init` in an existing shadcn app), then the component:

```sh
npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.344
npx shadcn@latest add ourostack/ouro-ui/page-shell#v1.3.344
```

More: [Installing](https://ui.ouroboros.bot/docs/installing.md).

```tsx
import { PageShell } from "@/components/ouro/page-shell/page-shell";
```

## Example

```tsx
<PageShell>
  <PageSection>
    <h2>Work</h2>
  </PageSection>
</PageShell>
```

## Use instead when

- Use `PageSection` inside it for the vertical rhythm between a page's sections, and `Stack` instead for spacing inside a column.

## Props

Type: `PageShellProps`.

| Prop | Type | Description |
| --- | --- | --- |
| `className` | `string` | Layout only: margins, grid placement. Appearance classes warn in development. |
| `ref` | `Ref<HTMLDivElement>` | Reaches the rendered element. |

## Native attributes

Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: PageShell merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

[^layout-classes]: test:registry/ouro/components/ouro/page-shell/page-shell.test.tsx::PageShell > lets the app's layout class win and warns about an appearance class verify:testExists(registry/ouro/components/ouro/page-shell/page-shell.test.tsx::PageShell > lets the app's layout class win and warns about an appearance class)
