conedevelopment/sprucecss

# Spruce CSS

Spruce CSS is a small, Sass-first framework. It styles native elements (typography, tables, forms, `details`, `dialog`, `progress`) with a few classes, and gives you **variables, mixins and functions** to write your own components. It has no grid system and only a handful of utility classes on purpose: write semantic HTML and component SCSS.

Docs: https://sprucecss.com/docs/ · Components: https://sprucecss.com/ui/

## Setup

```shell
npm install sprucecss
```

Configure Spruce on the **first** `@use` (Sass only allows configuration once), then generate the styles once:

# Block rhythm: one background, one padding

Every block owns its vertical padding (`padding-block: spacer-clamp('xl', 'xxl')`). On its own background that padding is the breathing room. But when two blocks meet **on the same background**, the bottom padding of the first and the top padding of the second add up to a gap twice as big as anywhere else, and the page looks broken.

**The rule:** if a block follows a block with the same background, its `padding-block-start` is `0`. The previous block's bottom padding already separates them. When the background changes, both keep their padding (the color change is the separator and each side needs its own room).

The page solves this, never the block: blocks stay reusable, and only the page knows what sits next to what.

## 1. Group consecutive blocks on the same background

The background of a page section comes from a wrapper (`.l-page__alt { background-color: color('surface-muted'); }`), not from the block. Blocks on the same alternate background share **one** wrapper; two wrappers of the same color are never siblings.

```html
<!-- Don't: two wrappers, the same background, a doubled gap. -->

# Spruce UI blocks and components

Spruce UI has three levels:

- **Components:** small, reusable UI (`.pricing-card`, `.toast`, `.tag-input`).
- **Blocks:** full-width page areas that combine components (`.pricing-block`, `.faq-block`).
- **Pages:** complete templates composed of blocks and components.

Before building a block or a page from scratch, check the online library: it may already exist (see the `sprucecss-library` skill).

## Block anatomy (always)

Every block follows this exact structure:

# Spruce UI library

The `sprucecss` npm package ships the framework only. The component library, **Spruce UI**, lives on the website: about 150 components, 50 blocks (full-width page sections) and 10 complete pages, all built with the Spruce conventions, tested in every design style, in dark mode and in RTL. Before you write a component, a block or a page, check whether the library already has it.

## 1. Find the item

Fetch the index once per task:

- **https://sprucecss.com/library.json**: every item with its `type` (`component`, `block`, `page`), `title`, `category`, `description`, the `markdown` URL and its dependencies.
- or **https://sprucecss.com/llms.txt**: the same list as Markdown, with the docs.

Pick by meaning, not by name: "a section with plans and prices" is the Pricing block or the Pricing Tiers block, "a slide-in cart" is the Cart Drawer. If two fit, read both descriptions and choose the closer one. For a whole page, start from the page template that's closest (a SaaS home, a portfolio, a course, a case study, a shop, a dashboard…) and swap or add blocks.

## 2. Fetch its endpoint

# Lists whose items sit side by side

Spruce styles every `ul` and `ol` as a vertical stack: the base typography includes `layout-stack(config('list-gap', $typography))` on them, a lobotomized owl:

```css
ul > * { margin-block: 0; }
ul > * + * { margin-block-start: 0.25rem; } /* list-gap */
```

That's right for a list of lines. But once the items are **not under each other** (a flex row, a cluster, a grid), the owl still pushes the second and every later item down: the first tag sits higher than the others, the first card of a grid row is shorter, and a grid's `gap` gets an extra margin on top.

## The rule

When a `ul` or `ol` lays out its `li` elements side by side (or in a grid with a `gap`), **clear the owl on the list's items and set their block padding to 0**:

# Spacing in Spruce CSS

In Spruce, the space between elements comes from the **parent**, almost never from the children. Pick the parent's tool by what its children are.

## 1. Sections under `__inner`: flex column with a gap

The `__inner` element of a block (and any wrapper whose direct children are sections: a heading group, a grid, a list, a form, a table) is a flex column with a gap:

```scss
.features-block {
  &__inner {
    display: flex;
    flex-direction: column;
    gap: spacer('l');

# Spruce CSS design styles

A **style** is a named set of design tokens, colors and a few extra rules. It changes how the *same markup* looks: no class names change. Spruce v3 ships eight presets: `minimal`, `brutalist`, `soft`, `glass`, `corporate`, `playful`, `editorial`, `terminal`.

## Turn styles on

Styles work through CSS custom properties, so the custom property mode is required:

```scss
@use 'sprucecss/scss/spruce' with (
  $settings: (
    'css-custom-properties': true,
    'styles': (
      'attribute': 'data-spruce-style', // the attribute name

# Brutalist style for Spruce CSS

Neo-brutalism: raw, loud and confident. Thick black outlines, hard offset shadows and saturated yellow/pink.

**Good for:** Landing pages, creative portfolios, indie products, event sites, campaigns.

## Enable it

```html
<html data-spruce-style="brutalist">
```

```scss
@use 'sprucecss/scss/spruce' with (

# Corporate style for Spruce CSS

Enterprise and dependable, inspired by design systems like IBM Carbon: dense, structured, unambiguous.

**Good for:** B2B products, admin panels, internal tools, banking, government and data-heavy apps.

## Enable it

```html
<html data-spruce-style="corporate">
```

```scss
@use 'sprucecss/scss/spruce' with (

# Editorial style for Spruce CSS

Magazine and print: literary, classic and elegant. Serif headings over sans-serif text, paper tones and a single ink-red accent.

**Good for:** Blogs, publications, long-form articles, newsletters, books, cultural institutions, law firms.

## Enable it

```html
<html data-spruce-style="editorial">
```

```scss
@use 'sprucecss/scss/spruce' with (

# Glass style for Spruce CSS

Glassmorphism: depth and light. Frosted, translucent surfaces float over a soft pastel mesh backdrop.

**Good for:** Hero sections, media and music apps, crypto/fintech dashboards, product launches, widgets.

## Enable it

```html
<html data-spruce-style="glass">
```

```scss
@use 'sprucecss/scss/spruce' with (

# Minimal style for Spruce CSS

Quiet, precise, monochrome. Think documentation sites, developer tools and editorial products where content is the hero.

**Good for:** SaaS dashboards, docs, portfolios, developer tools, settings pages.

## Enable it

```html
<html data-spruce-style="minimal">
```

```scss
@use 'sprucecss/scss/spruce' with (

# Playful style for Spruce CSS

Bubbly, vivid and tactile: candy colors, chunky outlines and buttons you want to press.

**Good for:** Kids and education, games, community apps, creative tools, marketing sites with personality.

## Enable it

```html
<html data-spruce-style="playful">
```

```scss
@use 'sprucecss/scss/spruce' with (

# Soft style for Spruce CSS

Soft UI: friendly, airy and calm, with pastel surfaces and large diffused shadows.

**Good for:** Consumer apps, onboarding flows, wellness and education products, mobile-first web apps.

## Enable it

```html
<html data-spruce-style="soft">
```

```scss
@use 'sprucecss/scss/spruce' with (

# Terminal style for Spruce CSS

Retro command line: phosphor green on near-black, monospace everything, a subtle glow.

**Good for:** Developer tools, CLI docs, hacker/security events, retro games, easter-egg modes.

## Enable it

```html
<html data-spruce-style="terminal">
```

```scss
@use 'sprucecss/scss/spruce' with (