half-built-ui

About

npm install @half-built/css @half-built/astro @half-built/tooling

• @half-built/css
• @half-built/astro
• @half-built/tooling

Frame

import Masthead from "@half-built/astro/components/Masthead.astro";
import Footer from "@half-built/astro/components/Footer.astro";
import ThemeToggle from "@half-built/astro/components/ThemeToggle.astro";
import TwoColumn from "@half-built/astro/components/TwoColumn.astro";

Header title and search

The header's title slot replaces the text inside the home link. The centering, the boxed tagline, and the heading level stay with the package, and the slotted element's own class carries any font change. With the slot empty, siteName renders as plain text. Passing searchAction={false} removes the search button, flyout, and form from the header. This site does that, because it has no search page.

---
import Masthead from "@half-built/astro/components/Masthead.astro";
---

<Masthead
  siteName="Sample Site"
  tagline="A sample tagline"
  nav={nav}
  socials={socials}
  dateStr={dateStr}
  searchAction={false}
>
  <span slot="title" class="wordmark">Sample <em>Site</em></span>
</Masthead>

TwoColumn is the page row. It holds the main column and a sidebar. The sidebar takes 30% of the row and stacks under the main column at the sidebar breakpoint. The frame below stands in for the page.

Cards

import PostCard from "@half-built/astro/components/PostCard.astro";
import CategoryCard from "@half-built/astro/components/CategoryCard.astro";
import { deriveExcerpt } from "@half-built/astro/lib/excerpt.ts";
import ExcerptStart from "@half-built/astro/content/ExcerptStart.astro";

The sample post body is passed through deriveExcerpt to produce the card's text. Text before the marker is not included.

Components

import Pagination from "@half-built/astro/components/Pagination.astro";
import PostNavigation from "@half-built/astro/components/PostNavigation.astro";
import Widget from "@half-built/astro/components/Widget.astro";
import LinkListWidget from "@half-built/astro/components/LinkListWidget.astro";
import Subscribe from "@half-built/astro/components/Subscribe.astro";
import Button from "@half-built/astro/content/Button.astro";
import Callout from "@half-built/astro/content/Callout.astro";
import EditorNote from "@half-built/astro/content/EditorNote.astro";
import WhenPublished from "@half-built/astro/content/WhenPublished.astro";
import PostLink from "@half-built/astro/content/PostLink.astro";
import Group from "@half-built/astro/content/Group.astro";
import CodeBlock from "@half-built/astro/content/CodeBlock.astro";
import Spacer from "@half-built/astro/content/Spacer.astro";
import Quote from "@half-built/astro/content/Quote.astro";
import Walkthrough from "@half-built/astro/content/Walkthrough.astro";
import Step from "@half-built/astro/content/Step.astro";
import Gallery from "@half-built/astro/content/Gallery.astro";
import GalleryImage from "@half-built/astro/content/GalleryImage.astro";
import BlogImage from "@half-built/astro/content/BlogImage.astro";
import MediaText from "@half-built/astro/content/MediaText.astro";
import Popout from "@half-built/astro/components/Popout.astro";

Pagination

Pagination is the numbered row at the bottom of an archive page. It renders nothing when there is only one page.

Post navigation

PostNavigation is the pair of links at the end of a post. The newer post is on the left and the older post is on the right. This matches the newest-first order of the archives.

Link list widget and Widget

Widget is a heading above arbitrary content. LinkListWidget is a Widget filled with a list of links and their counts.

Stat ledger

StatLedger sets a few figures side by side in one ruled box, a label over each value. One figure can take the accent. It is a description list, so a screen reader pairs each label with its value, and it stacks into one column at phone width.

Meter

Meter shows how far a count has come toward its total, in ruled segments. It carries role="meter" with the value and a text reading, and it needs no script. The value is clamped to the range, so an overshoot fills the bar and a total of zero leaves it empty. A missing value, which is not a finite number, reads as empty too.

Popout

Popout holds a short note behind a cell in a data table. It is for detail that is worth keeping but does not need its own column. On a wide screen it opens below its trigger, or above it when there is no room below. It closes automatically when the trigger scrolls out of view, when keyboard focus leaves it, or when the window crosses into phone width. On a phone it opens as a sheet from the bottom of the screen, with the row name as its caption. The layout loads popout.css and calls mountPopouts once.

---
import "@half-built/css/popout.css";
---

<script>
  import { mountPopouts } from "@half-built/astro/scripts/popout.ts";

  mountPopouts(document);
</script>

---
import Popout from "@half-built/astro/components/Popout.astro";
---

<Popout label="Row one">
  A note can contain a <a href="#components">link</a> and
  <code>inline code</code>.
</Popout>

Path player

The path player opens in the plate modal and adds playback controls and a timeline. The caller supplies the samples, the tracks under the stage, and the stage itself. The stage in this demo is a point moving on a closed curve. When reduced motion is set, the player opens paused.

Open the path player

---
import "@half-built/css/plate-modal.css";
import "@half-built/css/path-player.css";
---

<script>
  import { createPathPlayer } from "@half-built/astro/scripts/path-player.ts";

  const player = createPathPlayer(document, {
    title, source, caption, duration, samples, tracks,
    buildStage: (viewbox) => { /* append the stage, return true */ },
    sink: { start, move, stop },
  });

  button.addEventListener("click", () => player.open(button));
</script>

Plate frame

The plate frame is the plate modal's frame drawn inline: four accent corners around a plate with the surface and shadow. An icon box with .plate-frame-corner sits on the plate's top-right corner, where the modal puts its close box, and can open the full view. The corners come from the outer box's background, so the markup adds no elements for them. At phone width the corners drop and the box moves inside the plate, as in the modal.

Subscribe

Subscribe is a standard form with a method and an action, so it submits with JavaScript turned off. Its text is in named slots and can be replaced without forking the component. Its status lines can be replaced through the messages prop.

Button

Button has four variants and two sizes.

Plain Shaded Accent 1 Accent 2, large

A single call to action uses the centered row.

Centered call to action

Callout

Callout sets a passage apart from the body text. It is used for caveats and warnings the reader should not skip. The type sets the label and the line color.

Editor's note

EditorNote is a note to the author that only renders on a dev server. A production build outputs nothing for it, so it can stay in published content as a reminder. This one is forced visible with the shown prop.

When published and Post link

Both components take the site's post collection as a prop and do not read any content themselves. PostLink resolves a slug to the post's dated URL at build time. While the post is a draft, it renders plain text instead of a link. WhenPublished renders its content only after the named post is published. Its optional fallback slot renders until then. The sample collection here has one published post and one draft.

This passage is visible because its post is published. It links to the sample post. The URL was resolved from the slug.

This sentence names the sample draft in plain text because the post is still a draft. It becomes a link when the post is published.

This fallback stands in while the draft is unpublished.

Group

Code block

def read_ir(code):
    return "power" if code == 0x40BF else "unknown"

Spacer

A fixed-height spacer sits below this paragraph.

Normal flow resumes here, after the spacer.

Quote

A quoted line, with an attribution footer.

Walkthrough and Step

1. 
   First step. One placeholder photo beside its text.
2. 
   Second step. The step number is on a chip in the corner of the image.

Gallery

Blog image

AI Art

Media text

CSS primitives

import "@half-built/css/tokens";
import "@half-built/css/prose.css";
import "@half-built/css/patterns.css";
import Palette from "@half-built/astro/content/Palette.astro";

Every table in the system uses this boxed style. Wide tables scroll inside their own box, so the page never scrolls sideways.

This wider table scrolls in its own box. It lists every color primitive in the sheet, with one row per family and one column per stop.

The token roles that components read, with the value of each in the current theme and palette.

The fluid type sizes. Each line is set at its own size and shows the token name.

• --font-size-xs Sample text
• --font-size-sm Sample text
• --font-size-base Sample text
• --font-size-md Sample text
• --font-size-lg Sample text
• --font-size-xl Sample text
• --font-size-xxl Sample text

Placeholder body copy with inline code and a placeholder link.

A placeholder blockquote in a gray box.

• Placeholder list item one
• Placeholder list item two

A sentence with a footnote reference.¹ A claim with three sources stacked.^2,3,4