# Responsive Design

Sovrium's responsive system is built on **breakpoints** defined in `theme.breakpoints`. Each breakpoint becomes a min-width media query, and component props can be overridden per breakpoint for mobile-first layouts.

## `theme.breakpoints`

A map of breakpoint names to pixel values. Names are lowercase alphanumeric; values are pixel strings.

| Property | Description                                                                   |
| -------- | ----------------------------------------------------------------------------- |
| key      | Breakpoint name (lowercase alphanumeric, e.g. `sm`, `md`, `lg`, `xl`, `2xl`). |
| value    | Min-width threshold as a pixel string (e.g. `'640px'`, `'768px'`).            |

```yaml
theme:
  breakpoints:
    sm: '640px'
    md: '768px'
    lg: '1024px'
    xl: '1280px'
    '2xl': '1536px'
```

These map to the standard responsive tiers:

| Breakpoint | Min width | Typical target |
| ---------- | --------- | -------------- |
| `sm`       | `640px`   | Large mobile   |
| `md`       | `768px`   | Tablet         |
| `lg`       | `1024px`  | Laptop         |
| `xl`       | `1280px`  | Desktop        |
| `2xl`      | `1536px`  | Large desktop  |

:::callout
**Values must be pixel strings.** Each breakpoint value must match the `<number>px` format (e.g. `'768px'`). Non-pixel units (`rem`, `em`, `%`) are rejected by the schema.
:::

## Per-breakpoint overrides

Breakpoints power Tailwind's mobile-first utility variants. A base utility applies at all sizes; a prefixed variant (`md:`, `lg:`, …) applies from that breakpoint up. This is how a single component adapts across screen sizes.

```yaml
pages:
  - name: home
    path: /
    components:
      - type: container
        element: section
        props:
          # 1 column on mobile, 2 from md, 3 from lg
          className: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4'
        children:
          - { type: card, props: { className: 'p-4 md:p-6' } }
          - { type: card, props: { className: 'p-4 md:p-6' } }
          - { type: card, props: { className: 'p-4 md:p-6' } }
```

In the example above:

- `grid-cols-1` applies on all screens.
- `md:grid-cols-2` overrides it from `768px` up.
- `lg:grid-cols-3` overrides it again from `1024px` up.
- `p-4` is the base padding; `md:p-6` increases it from the `md` breakpoint.

:::callout
**Mobile-first.** Always declare the smallest layout as the base (unprefixed) utility, then layer larger-screen overrides with breakpoint prefixes. This guarantees a sensible default on the smallest viewport before any media query matches.
:::

## Custom breakpoints

Define your own names alongside or instead of the standard tiers. A custom breakpoint generates a matching utility prefix.

```yaml
theme:
  breakpoints:
    phone: '480px'
    tablet: '834px'
    wide: '1440px'
```

```yaml
props:
  className: 'flex-col tablet:flex-row wide:gap-12'
```

## Next steps

- [Theme](/en/docs/theme) — the full theme token reference.
- [Animations](/en/docs/animations) — keyframe and motion tokens.
- [Pages Overview](/en/docs/pages-overview) — component props and the `className` prop.