raam

raam (estonian) ˈrɑːm n. frame.

Beautifully boring cosmetic-free React.js components for structure and layout.

Use raam's layout primitives to build resilient theme-driven designs fast.


Components

  1. Wrap
  2. Inline
  3. Stack
  4. Feature Candidates

Wrap

A Flex-based layout that renders and 'wraps' children inline spaced by the defined gap.

Here gap is accessing the value from theme.space[3].

Responsive

As the gap prop is powered by Styled System, you have the ability to create responsive styles.

Here gap is accessing the value from theme.space[3], then theme.space[4] at breakpoint[1] etc.

Example

Let's take a look at a more real-world example; a "tag"-list at the bottom of an article:

Tags

  • Tag 1
  • Tag 2
  • Tag 3
  • Tag 4
  • Tag 5
  • Tag 6
  • Tag 7
  • Tag 8

Inline

If you'd rather let items flow elegantly in a single line, make use of Inline.

Scroll behaviour can be removed with an overflow: 'hidden'.

or with some more chaotic values…

Stack

Popularised by Seek's "Braid", a Flex-based layout that renders children on top of each other, spaced by the defined gap.

"Hold up, why don't you just…"

  • "…use display: grid;"
    Grid is fantastic for page layouts, but has its caveats for a 'simple' Stack:
  • "…make Inline and Stack one component"?

Flex

A display: flex;-based layout primitive that aims to address the gap.

Stack, Wrap and Inline are all effectively "presets" of Flex. Don't like that? It's OK, you can use Flex directly without opinionated defaults.

Caveats

TL;DR: Mind the Gap

At the time of raam's release, usage of gap in flex-based layouts is only supported by Firefox. To address this shortcoming, fallbacks are used:

  1. In nowrap based layouts, margins are used in a single direction excluding the first-child.
  2. In wrap based layouts, negative margins are used on the outer component to counteract margins inside.
    It will not affect adjacent margins, but you will experience issues if you try to adjust it directly - instead consider wrapping the element.

Feature Candidates

Article

A layout primitive to control vertical rhythm and flow for typographic content.


Getting Started

Installation

WIP

This project is in development and comes with caveats:

  1. Only supports React.js apps with Emotion or Theme UI pre-installed (for the time being).
  2. Prone to regular unannounced changes.

npm i raam --save
or
yarn add raam

Configuration

All components use a shared set of props:

  • gap: a dynamic prop that aims to resolve the lack of gap support for display: flex; in most browsers.

    It accepts a key from theme.space (as a string or number), but if that's not found it'll render the provided string (e.g. em or rem) or number as a px value.

  • Color, Space and Flexbox (excluding order, alignSelf and justifySelf) props from Styled System.

  • as: change the HTML element rendered (via Emotion).

    raam makes an opinionated choice on how to render a component's children based on the element provided:

    aschildren rendered as
    div (default)div
    olli (with list-style-type reset)
    ulli (with list-style-type reset)
    spanspan
    pspan
    h1-h6span
  • css: apply styles to the component (via Emotion).

    Note: Use with caution, modifying the margin/padding may not behave as expected.

  • sx: apply themed styles to the component (via Theme UI).

    Note: Heavily recommended to install Theme UI before using. As with css, use with caution.

Acknowledgements

Without these projects/people, this project wouldn't exist…