Skip to content

Article

The body is the default slot, so Markdown or a CMS rich text field renders straight into it with prose styles for headings, lists, quotes, images and code. Give each heading an id that matches the toc entries.

Notes

Why we rebuilt Samla

What changed when the library moved to Astro components.

Placeholder for a header image
The demo site, composed from the rebuilt library.

The first version of Samla kept a separate HTML component library beside the site. Every change had to be made twice, and the two copies drifted. Here is what we changed.

Each element, component and section is now one .astro file. Its markup, styles and any script live together, and a built site is still ordinary static HTML.

Component CSS sits in a scoped <style> block. Shared values live in tokens.css, and global.css keeps only document-level rules.

Placeholder for a diagram of the library layers

Most pieces need no script at all. Where one does, it ships with that piece and nowhere else. Our rule is simple:

  • Start from native HTML
  • Add JavaScript only where it earns its place
  • Keep the page usable before it loads

A piece should work before its script runs.

A component isn’t done until a clean Astro site can render it:

import Statement from "@samla/ui/Statement.astro";

The demo site is that clean consumer, so every change is checked there as well as in the docs.

  1. One copy of the markup is easier to keep right than two.
  2. Scoped styles stop one piece breaking another.
  3. Most pieces never needed JavaScript.

Related articles

  • title: required; lead, meta and tag optional
  • image, imageAlt, caption: header image shown wide under the title
  • toc: list of { id, label, level } (level is 2 or 3); shows a contents list that becomes a sticky sidebar from desktop width (data-layout="split"); tocTitle changes its heading
  • author: { name, role, bio, image, href }, shown in a Profile box after the body
  • related: list of { title, href, excerpt, tag, image }, shown as Cards beneath the article; relatedTitle changes the heading
  • shareUrl: shows email, LinkedIn and X share links, plus a copy link button when the Clipboard API is available
<Article
title="Why we rebuilt Samla"
meta="12 September 2026 · 5 minute read"
tag="Notes"
image="/images/rebuild.jpg"
toc={[
{ id: "one-source-of-markup", label: "One source of markup" },
{ id: "scoped-styles", label: "Scoped styles", level: 3 },
]}
author={{ name: "Samla team", role: "Maintainers" }}
related={related}
shareUrl="https://samla.luministic.co.uk/notes/rebuild/"
>
<Content />
</Article>
Minimal: no image, contents or extras

Adding a piece to Samla

Check the existing components first. Add a piece when a real site needs it, and keep it in one .astro file.

Give it one block class, such as .sui-card, and express variation with a data-* attribute from the table in AGENTS.md.