Installation

Install

To install unitone CSS in your project, execute the following command in a terminal.

$ npm install --save-dev @inc2734/unitone-css

Import CSS

To import CSS for unitone CSS, @use in your main SCSS file. In the case of HTML, you can also use <link /> to load CSS.

When you compile with the Dart Sass CLI directly, package specifiers such as @inc2734/unitone-css/... are not resolved automatically. Use either --load-path=node_modules or the Node package importer with pkg:.

@use '@inc2734/unitone-css/src/app';

@use '@inc2734/unitone-css/src/settings';
@use '@inc2734/unitone-css/src/layout-primitives';
@use '@inc2734/unitone-css/src/behaviors';
@use '@inc2734/unitone-css/src/utilities';

@use '@inc2734/unitone-css/src/layout-primitives/vertical-writing';
 
@include vertical-writing.vertical-writing();

<link rel="stylesheet" href="/node_modules/@inc2734/unitone-css/dist/app.css" />

Examples for the Dart Sass CLI:

sass --load-path=node_modules --no-source-map src/css/app/global-styles.scss:dist/css/app/global-styles.css

@use 'pkg:@inc2734/unitone-css/src/settings';
@use 'pkg:@inc2734/unitone-css/src/layout-primitives';
@use 'pkg:@inc2734/unitone-css/src/behaviors';
@use 'pkg:@inc2734/unitone-css/src/utilities';

sass --pkg-importer=node --no-source-map src/css/app/global-styles.scss:dist/css/app/global-styles.css

Import JavaScript

To import JavaScript for unitone CSS, import in your main JavaScript file. In the case of HTML, you can also use <script /> to load JavaScript.

import '@inc2734/unitone-css/app';

import '@inc2734/unitone-css/layout-primitives';
import '@inc2734/unitone-css/behaviors';

<script src="/node_modules/@inc2734/unitone-css/dist/app.js" defer></script>

When using server-side rendering frameworks, load this script with the framework’s equivalent of <script defer>. The all-in entry loads the marquee and vertical-writing layout primitive scripts, plus the divider and stairs behaviors. Individual entries such as @inc2734/unitone-css/layout-primitives/vertical-writing/behavior and @inc2734/unitone-css/behaviors/dividers are also available when you only need a specific entry.

These entries initialize divider and stairs behaviors when their layout attributes are added to an existing element, and stop and clear their generated state when the behavior is removed. They also automatically stop observing removed elements and initialize them again when they are reinserted. Moving an element within the document in the same DOM update keeps its existing observers.

If you call dividersResizeObserver, stairsResizeObserver, verticalsResizeObserver, or marqueeResizeObserver directly from @inc2734/unitone-css/library, the returned function stops observation and cancels queued updates. Existing calls that ignore the return value continue to work. Direct calls manage their own lifetime:

import { marqueeResizeObserver } from '@inc2734/unitone-css/library';
 
const stopObserving = marqueeResizeObserver(element);
 
// Call when the manually initialized element is no longer needed.
stopObserving();

Stopping observation leaves the current styles and generated content in place. Call the observer function again to resume updates. The returned cleanup function can be called more than once.

Import React Components

When you use layout primitives as React components, import each component from @inc2734/unitone-css/layout-primitives/<name>/react. These entries include the behaviors required by that component, so no additional behavior import is required for React usage.

Stack, Cluster, WithSidebar, ResponsiveGrid, Switcher, VerticalWriting, and Marquee are client entries and can be imported from React Server Components. CSS-only primitives remain usable as Server Components. Props passed across a server-to-client boundary must follow React’s serialization rules; define event handlers and custom tagName components inside a client module.

The JavaScript-backed React components manage their own observers after hydration and refresh their layouts after React commits. Divider and stairs props can be enabled, changed, disabled, and enabled again without remounting. Removing a component stops its observers and cancels queued updates. Forwarded refs follow the current DOM element, including changes to tagName; the VerticalWriting ref targets the inner writing element.

The HTML auto-initializers skip elements marked as React-managed, so importing the all-in script alongside these components does not initialize them twice or modify their server HTML before hydration. Calling a layout setter or observer helper on a React-managed element requests a refresh from its component; a manually returned cleanup does not stop the component’s own observers. Before hydration, such requests leave the server HTML unchanged.

These guarantees apply to the provided React components. Handwritten JSX using data-unitone-layout needs explicit coordination between hydration and any HTML behavior initialization.

import { Decorator } from '@inc2734/unitone-css/layout-primitives/decorator/react';
import { VerticalWriting } from '@inc2734/unitone-css/layout-primitives/vertical-writing/react';

Using Layout Primitives

The unitone CSS layout primitives can be used with the following code.

For the detailed description of each layout primitives, see the Layout Primitives page.

<div data-unitone-layout="decorator -padding:1">
	<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cill</p>
</div>

import { Decorator } from '@inc2734/unitone-css/layout-primitives/decorator/react';
 
<Decorator padding={1}>
	<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cill</p>
</Decorator>