UI Library

Install

Install from npm with the JSX and type tooling peers:

npm install @macavitymadcap/hyper-dank-ui hono typescript

Package: view on npm.

Import components from server JSX and import the CSS through the browser asset pipeline. Importing a component in server code does not automatically load browser styles.

import { Button, Card, FormField, HxForm, StagedForm, Switch } from "@macavitymadcap/hyper-dank-ui";
import "@macavitymadcap/hyper-dank-ui/styles.css";

export function SettingsForm() {
  return (
    <Card as="section">
      <HxForm action="/settings" method="post" hx-post="/settings" hx-target="#settings-panel">
        <FormField id="display-name" label="Display name" name="displayName" required />
        <Switch id="notifications" label="Notifications" name="notifications" value="enabled" />
        <Button>Save settings</Button>
      </HxForm>
    </Card>
  );
}

The CSS export preserves generic hooks such as .button[data-variant="ghost"], .switch[data-variant="compact"], and .form-field. Product layout and visual identity should layer after the package CSS.

Component API

Storybook is the canonical rendered reference. Shared package examples are grouped under Components/Shared, while Walking Pace examples are grouped under Components/Reference App. Individual Storybook examples are published at /storybook/.

Composition Patterns

Use HxForm when a control must work as normal HTML first and become fragment-driven when HTMX is available.

<HxForm
  action="/items"
  method="post"
  hx-post="/items"
  hx-target="#items-list"
  hx-swap="outerHTML"
>
  <FormField id="title" label="Title" name="title" required />
  <Button>Add item</Button>
</HxForm>

Staged Forms

Use StagedForm inside HxForm when a long form needs a shared progress list and current-step panel, but the app still owns which steps are available. Steps accept complete, current, available, unavailable, and error states plus optional native href and hx-* attributes. The current panel can compose Fieldset, FormField, ValidationSummary, ButtonGroup, and native submit buttons.

<HxForm action="/articles/new" method="post" hx-post="/articles/new/stage" hx-target="#stages">
  <StagedForm
    id="stages"
    currentStepId="content"
    steps={[
      { id: "basics", label: "Basics", status: "complete", href: "/articles/new?stage=basics" },
      { id: "content", label: "Content", status: "current" },
      { id: "review", label: "Review", status: "unavailable" },
    ]}
    actions={<Button type="submit">Continue</Button>}
  >
    <FormField id="body" label="Body" name="body" />
  </StagedForm>
</HxForm>

Validation rules, dependent-step eligibility, saved data, permissions, and redirects stay in the route or service layer. Branching workflows and client-side wizard engines are deliberately outside the shared UI contract.

BasicGraph

Use BasicGraph when a page needs a small static chart for comparison or trend context. It renders an SVG with role="img", a connected title and description, and a visible caption. The component is for already-prepared values; apps still own analytics queries, aggregation, permissions, live data, and any interactive exploration.

<BasicGraph
  id="content-activity"
  title="Content activity"
  summary="Published content is trending upwards across three review periods."
  kind="line"
  data={[
    { label: "Week 1", value: 8 },
    { label: "Week 2", value: 13 },
    { label: "Week 3", value: 18 },
  ]}
/>

The component accepts kind, data, max, summary, valueFormatter, width, height, and className. Its CSS uses currentColor and --hd-accent, so the graph can follow light, dark, or app-specific themes without changing the JSX contract.

Data Tables

Use ScrollableTable for semantic table markup that needs responsive column tracks, sticky headers, scrollable bodies, loading and empty composition, pagination, and row-action columns. Column metadata can expose sortDirection as aria-sort, while header content can be a normal link to an app-owned sorted route. TableFilterSummary provides a polite summary of result counts, active filters, and reset links.

Hyper-Dank does not sort, filter, persist column preferences, store selected rows, or run mutations. Build those behaviours in the consuming app, then pass the resulting rows, links, labels, and preferences into the shared markup primitives.

Feedback Vocabulary

Use info, success, warning, and danger for page-level notification severity. StatusSymbol also accepts neutral for compact inline metadata. Each marker exposes a shape hook, not only a colour: circle for information, check for success, triangle for warning, octagon for danger, and dot for neutral.

NotificationBanner maps warning and danger to assertive alerts, while info and success remain polite status regions. Use it for page-level events. Use Notice for local panel or form feedback, ValidationSummary for linked form errors, Progress and LoadingIndicator for async work, and StatusSummary or Badge for compact dashboard metadata. Toast-style regions should stay static landmarks in shared markup; client queues, timers, dismissal, stores, and persistence belong in the consuming app.