REFERENCE

LayoutKit Docs

A tiny pure-CSS layout vocabulary for readable app structure. Use lk-* tags to make layout intent visible while native semantic HTML carries document meaning.

Install Scope Primitives Attributes Helpers Tokens Accessibility TSX/JSX Browser support Security

Install and load CSS

Load LayoutKit early in the document <head>, or import it at the root/global CSS level in a framework. If the CSS does not load, lk-* tags are plain unknown elements.

npm install layoutkit-css

import "layoutkit-css/layoutkit.css";

<link rel="stylesheet" href="https://unpkg.com/layoutkit-css/layoutkit.css">

Scope

LayoutKit covers common layout primitives: stack, row, center, spread, grid, box, card, cluster, switcher, sidebar, cover, spacer, divider, aspect ratio, and scroll area.

Non-goals

No buttons, forms, typography system, color themes, icons, animation system, JavaScript behavior, stateful app shell, data table styling, component library, or design system replacement.

Semantic HTML first

LayoutKit is semantic to developers, not to the browser accessibility tree. It should not replace main, nav, section, article, header, footer, headings, buttons, links, lists, tables, or form controls.

Good

<main>
  <section aria-labelledby="dashboard-heading">
    <lk-stack gap="lg">
      <h1 id="dashboard-heading">Dashboard</h1>
      <article><h2>Open orders</h2></article>
    </lk-stack>
  </section>
</main>

Bad

<lk-box>
  <lk-stack>
    <lk-text>Dashboard</lk-text>
  </lk-stack>
</lk-box>

This loses native document meaning.

Basic primitives

Tag	Purpose	Common attributes
`lk-stack`	Vertical flow	gap, padding, align, justify, place, fill, full-height, wrap, width
`lk-row`	Horizontal flow	gap, padding, align, justify, place, wrap, reverse
`lk-center`	Centered layout	fill, full-height, inline, horizontal, vertical, place
`lk-box`	Block wrapper	padding, fill, width, flow
`lk-card`	Neutral padded block	padding, radius, surface, border, width, flow
`lk-spread`	Space-between row	align, padding, place
`lk-grid`	Grid layout	cols, rows, responsive, min, gap, col-gap, row-gap, flow, place-items
`lk-cluster`	Wrapping group	gap, place
`lk-switcher`	Intrinsic row-to-stack layout	gap
`lk-sidebar`	Wrapping side/content layout	gap, side
`lk-cover`	Min-height cover region	gap, center
`lk-spacer`	Flexible or fixed space	size
`lk-divider`	Visual divider	orientation, thickness
`lk-aspect-ratio`	Aspect-ratio wrapper	ratio
`lk-scroll-area`	Constrained scroll container	direction, max-h

Attribute reference

Attributes map to stable layout behavior. They are not a mirror of every CSS property.

Spacing

gap, padding, col-gap, row-gap: none, px, xs through 3xl, and the finite numeric scale.

Alignment

align, justify, place, place-items, and center cover common flex and grid alignment.

Sizing

fill, full-height, width, size, min, max-h, and custom properties cover common sizing needs.

Frozen convenience helpers

lk-card, lk-text, and lk-weight are intentionally small convenience helpers. They are not the start of a component or typography system, and new visual styling primitives should be rejected unless they directly support layout.

Design token customization

LayoutKit variables fall back to default values, but first look for app-level variables such as --space-md, --text-md, and --radius-md.

:root {
  --lk-space-sm: var(--space-sm, 0.5rem);
  --lk-space-md: var(--space-md, 1rem);
  --lk-space-lg: var(--space-lg, 1.5rem);
  --lk-text-md: var(--text-md, 1rem);
  --lk-radius-md: var(--radius-md, 0.75rem);
}

Map LayoutKit to your app tokens:

:root {
  --space-sm: var(--space-2);
  --space-md: var(--space-4);
  --space-lg: var(--space-6);
}

Accessibility

LayoutKit wraps and arranges semantic HTML.
LayoutKit does not replace semantic HTML.
Do not put click handlers on lk-* elements. Use button or a.
Do not use lk-* elements as headings, lists, tables, forms, landmarks, or controls.
If a LayoutKit wrapper has no semantic purpose, it usually does not need ARIA.
Do not add ARIA roles just to make layout wrappers seem semantic.
Prefer native HTML first.
LayoutKit should not interfere with focus order.
Avoid hiding overflow in ways that trap keyboard users.
Scroll containers should remain keyboard and screen-reader usable.
LayoutKit provides layout behavior only. Accessibility still depends on the underlying HTML and application code.

Examples

Form layout

<form action="/settings" method="post">
  <lk-stack gap="md">
    <label>Name <input name="name"></label>
    <button type="submit">Save</button>
  </lk-stack>
</form>

Scroll area

<section aria-labelledby="activity">
  <h2 id="activity">Recent activity</h2>
  <lk-scroll-area max-h="md">
    <ol><li>Order opened</li></ol>
  </lk-scroll-area>
</section>

Using LayoutKit with TSX/JSX

The package includes jsx.d.ts. It only teaches TypeScript about known custom tags and attributes. No runtime JavaScript is required.

{
  "compilerOptions": {
    "types": ["layoutkit-css"]
  }
}

Browser support

LayoutKit targets modern evergreen browsers with support for custom properties, flexbox, grid, cascade layers, logical properties, aspect-ratio, svh, and color-mix().

Security and package verification

LayoutKit has no runtime JavaScript, no npm dependencies, no install scripts, no remote imports, and should not perform network requests.

npm pack layoutkit-css
tar -tzf layoutkit-css-*.tgz

GitHub repository npm package