npm install @vrembem/content

@use "@vrembem/content";

Options

Content is built as a Sass module. Sass options are used to control CSS output, while design token CSS variables control the styling of the component. Below are the available configuration options.

Sass

Content comes with the following Sass configuration options that can be set using either the config module or Sass with clause methods.

@use "@vrembem/content" with (
  $config: (
    // Controls whether module styles are output. This can be overridden on a per 
    // module basis using the `content-output-exceptions` config option.
    // @type boolean
    "content-output": true,

    // Modules to exclude from the output rule set in `content-output`
    // @type list
    "content-output-exceptions": (),

    // A map containing module names as keys and their preferred class selectors
    // @type map
    "content-classes": (
      "separator": "sep"
    ),

    // A prefix to apply to content class selectors. Provided value is automatically 
    // suffixed with a "-" character when applied.
    // @type string
    "content-prefix": "",

    // Used to output the heading styles and their font-size/line-height CSS 
    // variables. Should contain a key of the heading level to output and the 
    // value of a font-size and optional line-height (space separated).
    // @type map
    "content-headings": (
      "h1": 2.75em 1.1,
      "h2": 2em 1.25,
      "h3": 1.75em 1.3,
      "h4": 1.5em 1.35,
      "h5": 1.25em 1.4
    ),

    // Map modules to their preferred content selectors
    // @type map
    "content-selectors": (
      "h1": "> h1",
      "h2": "> h2",
      "h3": "> h3",
      "h4": "> h4",
      "h5": "> h5",
      "h6": "> h6",
      "link": ":not(div) > a",
      "list": "> ul, > ol",
      "code": ":not(pre) > code",
      "pre": "> pre",
      "blockquote": "> blockquote",
      "separator": "> hr"
    )
  )
);

Design tokens

Content uses design token CSS variables in a reference and fallback pattern. Variables are referenced in the component's styles but are not directly defined; instead, they are provided with sensible fallbacks.

--vb-content-foreground

var(--vb-foreground)

--vb-content-font-family

inherit

--vb-content-font-size

inherit

--vb-content-line-height

inherit

--vb-content-spacing

--vb-headings-foreground

var(--vb-foreground-strong)

--vb-headings-font-family

inherit

--vb-headings-font-weight

var(--vb-font-weight-semi-bold)

--vb-headings-line-height

inherit

--vb-link-foreground

var(--vb-foreground-accent)

--vb-link-foreground-hover

light-dark(oklch(from var(--vb-foreground-accent) calc(l - 0.1) c h), var(--vb-foreground-accent) calc(l + 0.1) c h)))

--vb-link-decoration

underline

--vb-link-decoration-hover

none

--vb-link-decoration-thickness

1px

--vb-link-underline-offset

2px

--vb-link-focus-ring

currentcolor dotted 1px

--vb-link-focus-ring-offset

0.125rem

--vb-list-indent

var(--vb-spacing-lg)

--vb-list-spacing

var(--vb-spacing-sm)

--vb-code-background

color-mix(in oklch, currentcolor 10%, transparent)

--vb-code-foreground

var(--vb-foreground-accent-alt)

--vb-code-border

var(--vb-border)

--vb-code-border-radius

var(--vb-border-radius)

--vb-code-font-size

var(--vb-font-size-sm)

--vb-code-padding

0.125rem 0.375rem

--vb-pre-background

var(--vb-background-alt)

--vb-pre-foreground

var(--vb-foreground-strong)

--vb-pre-border

none

--vb-pre-border-radius

var(--vb-border-radius)

--vb-pre-padding

var(--vb-spacing-md)

--vb-pre-font-size

var(--vb-font-size-sm)

--vb-blockquote-background

transparent

--vb-blockquote-foreground

currentcolor

--vb-blockquote-border

var(--vb-border)

--vb-blockquote-border-radius

var(--vb-border-radius)

--vb-blockquote-padding

var(--vb-spacing-md)

--vb-blockquote-spacing

var(--vb-spacing-md)

--vb-separator-border-width

var(--vb-border-width)

--vb-separator-border-style

var(--vb-border-style)

--vb-separator-border-color

var(--vb-border-color)

--vb-arrow-size

6px 4px

--vb-arrow-color

currentcolor

--vb-arrow-radius

2px

--vb-loading-size

1em

--vb-loading-duration

0.6s

--vb-loading-border

2px solid

--vb-loading-color

currentcolor

Output

Content modules each have their own output styles. These are all output by default when the content package is loaded. There are two ways to control which modules are output using the content-output and content-output-exceptions configuration options.

@include config.set("content-output", false);

@include config.set("content-output-exceptions", (
  "content", "headings"
));

Example

Use the content-output configuration to toggle output for all modules. Add exceptions to the content-output-exceptions list to override the output option for specific modules.

// Import the config module
@use "@vrembem/core/config";

// Disable the output of specific modules
@include config.set("content-output-exceptions", (
  "blockquote",
  "code",
  "list",
  "pre"
));

// Disable the output of all modules except for "content" and "headings"
@include config.set((
  "content-output": false
  "content-output-exceptions": (
    "content",
    "headings"
  )
));

Basic usage

The content component provides the .content wrapper class for styling blocks of HTML elements. It also makes available a number of element classes that can be applied directly when those styles are needed outside the context of a content wrapper.

<!-- Using the content wrapper -->
<div class="content">
  <h1>Heading</h1>
  <p>...</p>
  <ul>
    <li>...</li>
  </ul>
</div>

<!-- Using individual element classes -->
<h1 class="h1">...</h1>
<p>...</p>
<ul class="list">
  <li>...</li>
</ul>

The entire output of the content component is placed in @layer base. This allows all components and utilities to override the styles set by content and it's member modules.

To customize the class selectors used by modules, map the module name to your preferred class selector in the content-classes config option.

@include config.set("content-classes", (
  "content": "pros"
));

Provide a prefix to all content classes using the content-prefix config option.

@include config.set("content-prefix", "vb");
// Result: .content > .vb-content

The content module only applies styles to its direct children using the > child combinator. This is to allow nesting of other components within a content block and avoid style conflicts. Module specific content selectors are controlled using the content-selectors variable map.

@include config.set("content-selectors", (
  "h1": "> h1",
  "h2": "> h2",
  "h3": "> h3",
  // ...
));

"content-selectors": (
  "h1": "> h1",
  "h2": "> h2",
  "h3": "> h3",
  "h4": "> h4",
  "h5": "> h5",
  "h6": "> h6",
  "link": ":not(div) > a",
  "list": "> ul, > ol",
  "code": ":not(pre) > code",
  "pre": "> pre",
  "blockquote": "> blockquote",
  "separator": "> hr"
)

Modules

Below is a list of each content module, their class selectors, design token CSS variables, and intended usage. Modules that reference CSS variables are provided with sensible fallbacks.

headings

Section headings in HTML are represented by the <h1> through <h6> elements. This module helps style these elements by providing the .h1-.h6 CSS classes.

<h1 class="h1">...</h1>
<h2 class="h2">...</h2>
<h3 class="h3">...</h3>
<h4 class="h4">...</h4>
<h5 class="h5">...</h5>
<h6 class="h6">...</h6>

Headings output and scale is controlled by the content-headings configuration option.

@include config.set("content-headings", (
  "h1": 3em 1.2,
  "h2": 2em 1.6,
  // ...
));

"content-headings": (
  "h1": 2.75em,
  "h2": 2em,
  "h3": 1.75em,
  "h4": 1.5em,
  "h5": 1.25em,
  "h6": 1em
)

link

A link—usually represented by an anchor (<a>) HTML element with href attribute—creates the styles for a hyperlink to anything a URL can address. This module helps style these elements by providing the .link CSS class.

<a href="#" class="link">Link</a>

list

The list module helps add styles to unordered (<ul>) and ordered (<ol>) lists by providing the .list class.

<ul class="list">
  <li>One</li>
  <li>Two
    <ul>
      <li>One</li>
      <li>Two</li>
      <li>Three</li>
    </ul>
  </li>
  <li>Three</li>
</ul>

<ol class="list">
  ...
</ol>

code

The HTML code element displays its contents styled in a fashion intended to indicate that the text is a short fragment of computer code. This module helps style these elements by providing the .code CSS class.

<code class="code">a = 17</code>

pre

This module helps style the HTML <pre> element by providing the .pre CSS class. Whitespace inside this element is displayed as written.

<pre class="pre">
-----------------------------
| I'm an expert in my field |
-----------------------------
     \   ^__^
      \  (oo)\_______
         (__)\       )\/\
             ||----w |
             ||     ||
</pre>

blockquote

The HTML blockquote element is used for marking up extended quotations. This module helps style these elements by providing the .blockquote CSS class.

<blockquote class="blockquote" cite="...">
  <p>...</p>
  <footer>
    ...
    <cite>...</cite>
  </footer>
</blockquote>

separator

This module adds the .sep CSS classes which visually renders a horizontal separator. This is most commonly applied to an <hr> HTML element but can also be applied to a more generic <span> or <div> depending on the semantic context.

<hr class="sep" />

arrow

The arrow (caret) module provides classes for directional triangles drawn with CSS. These are typically applied to <span> elements and used along side other components as direction indicators.

<span class="arrow"></span>
<span class="arrow-up"></span>
<span class="arrow-left"></span>
<span class="arrow-right"></span>

Arrows are great for buttons or menu items to visually indicate when it reveals toggle-able content such as popovers or dropdowns.

<button class="button">
  <span>Button</span>
  <span class="arrow"></span>
</button>

loading-spinner

The loading-spinner module provides the .loading-spinner CSS class. A loading spinner is a visual indicator for when a process or action is taking place such as a loading state.

<span class="loading-spinner"></span>

sr-only

This module provides an accessibility class for rendering content meant only for screen readers. This keeps the content accessible in the DOM for screen readers while hiding it visually from all other users.

<p>
  The following content is for screen readers only:
  <span class="sr-only">Hello, screen readers!</span>
</p>