@haruhimemoe/ui

React components for the haruhime.moe osu! tools on Next.js. It ships the osu!-web-style palette as a Tailwind 4 theme, plus buttons, links, badges, form fields and confirms, filter controls (toggle and choice chips, a two-thumb range slider, a filter panel), a SegmentedControl view switch and a CopyField copy row, list and page layout pieces (Surface, LinkCard, CardGrid, StatList, LinkRow, SectionHeading, EmptyState, Progress, PrevNext, CodeChip), tables, osu! beatmap display pieces and player cards, a command palette (mod+k, with the defaults every tool shares), content section tooling (nav, search, index and page), brand pages and the site header, footer, tabs, account menu and page frame. Most components are Server Components. The few that need the browser carry "use client" in their own files, so you import everything from one place.

See every component in its states at haruhime.moe/ui. The page names the version it runs.

This README describes version 0.13.0. Anything marked "since 0.13.0" is not in 0.12.x, anything marked "since 0.12.0" is not in 0.11.x, anything marked "since 0.11.0" is not in 0.10.0, anything marked "since 0.10.0" is not in 0.9.0, anything marked "since 0.9.0" is not in 0.8.0, anything marked "since 0.8.0" is not in 0.7.0, anything marked "since 0.7.0" is not in 0.6.0, anything marked "since 0.6.0" is not in 0.5.0, anything marked "since 0.5.0" is not in 0.4.0, anything marked "since 0.4.0" is not in 0.3.0, anything marked "since 0.3.0" is not in 0.2.0, and anything marked "since 0.2.0" is not in 0.1.0. CHANGELOG.md lists what changed in each version.

• Next.js 16 (app router)
• React 19
• Tailwind CSS 4.1 or later, below 5

These are peer dependencies. The package is ESM only, and its engines field asks for Node.js 22.12 or later.

bun add @haruhimemoe/ui

If the app doesn't have the peers yet:

bun add next react react-dombun add -d tailwindcss @tailwindcss/postcss

1. Load Tailwind through PostCSS (skip this if the app already uses Tailwind 4). Without this file Next generates no utilities, and the components render unstyled with no build error.

// postcss.config.mjsexport default { plugins: { "@tailwindcss/postcss": {} } };

2. Import the theme after Tailwind in the app's global stylesheet:

/* src/app/globals.css */@import "tailwindcss";@import "@haruhimemoe/ui/theme.css";

The theme does three things:

• Adds the palette as Tailwind colors, so bg-b4, text-c1, border-h1 and the rest work in your own markup too.
• Adds a visible focus ring (h1, 2px) to everything on :focus-visible.
• Points Tailwind at the package's files with @source, so the classes the components use get generated. Without it the components render unstyled.

3. Load Nunito with next/font as the --font-nunito variable on <html>. The theme's font-sans uses it, and falls back to the system font without it.

import { Nunito } from "next/font/google";const nunito = Nunito({ subsets: ["latin"], variable: "--font-nunito", display: "swap" });// <html lang="en" className={nunito.variable}>

4. Pick a hue (optional). Every color comes from one --hue (default 333, pink). Set it on :root after the imports to recolor the whole app:

:root {  --hue: 200; /* blue */  --h2-l: 42%; /* keeps white text on primary buttons at 4.5:1 */}

At some hues the defaults drop below 4.5:1 contrast, so check yours. Two variables fix it (and --c2-l, --c3-l, --c4-l set the content steps' lightness, default 90%, 80%, 70%):

• --h2-l sets the lightness of h2 (default 45%). White text on h2 (primary buttons, the skip link) is under 4.5:1 for hues from about 23 to 205. Use 42% at hue 200, 35% at hue 150, or 31% for any hue.
• --h1-l sets the lightness of h1 (default 76% since 0.7.0, 70% before). At 76%, h1 text on b5 (links in cards and prose) is at or above 4.5:1 at every hue. On b4 ("Clear filters" in a filter panel) it dips under for hues from about 238 to 248. Use 77% there.

The theme is dark by default (color-scheme: dark).

Light scheme (since 0.20.0). Import theme-light.css after theme.css for a white page:

@import "tailwindcss";@import "@haruhimemoe/ui/theme.css";@import "@haruhimemoe/ui/theme-light.css";

Same components, same class names. It sets the lightness variables the palette reads (--b1-l to --b6-l, --c1-l to --c4-l): b5 is the page, b4 white cards, b6 code and wells, and c1 to c4 are tinted ink, c1 darkest. The highlights swap jobs: h1 (36%) is the dark accent for links, rings and filled chips, and h2 (85%) the pale fill under c1 text on primary buttons and selected tabs. Code tokens get dark values. The wordmark's white turns to c1 ink through --wordmark-ink. Every ink step stays at 4.5:1 on every surface at every hue. h1 does at the default hue; for hues from about 30 to 200 set --h1-l: 21%. Under prefers-contrast: more the lift is -8%, so ink and h1 get darker and h2 lighter.

5. Motion, contrast and touch (since 0.12.0). The theme follows three browser settings. There is no in-app toggle.

• Reduced motion. When the visitor asks for reduced motion (prefers-reduced-motion: reduce), every animation and transition finishes in 0.01ms and smooth scrolling turns off, in the kit and in your own markup. Put data-motion="essential" on an element whose movement is the message (a progress indicator): it and its children keep their motion. Tokens: duration-short (150ms: hovers, presses, color changes, and the default for every transition-*), duration-medium (250ms: panels, dialogs), duration-long (400ms: large surfaces), with ease-standard (the default), ease-enter and ease-exit. For motion JavaScript drives (an autoplay video, a canvas), read useMotionAllowed().
• More contrast. Under prefers-contrast: more, c2, c3, c4 and h1 get 8 points lighter and h2 4 points darker. Cards, chips, secondary and ghost buttons, neutral badges and the tabs track get a c4 edge; fields, code blocks and menus swap their b3 border for c4. The lift adds to your --h1-l and --h2-l. Set --contrast-lift: 0% on :root to opt out.
• Touch. coarse: is a variant for a touchscreen as the main pointer (@media (pointer: coarse), the same query as Tailwind's pointer-coarse:). Buttons at md, chips, checkbox and radio rows, tabs, menu items, palette rows and fields grow to 44px there, and fields use 16px text so iOS Safari doesn't zoom in. Undo it for one control with a class like coarse:h-9. A touchscreen laptop driven by its trackpad keeps the dense layout.

// src/app/layout.tsximport { PageShell, SiteFooter, SiteHeader } from "@haruhimemoe/ui";import { Nunito } from "next/font/google";import Link from "next/link";import type { ReactNode } from "react";import "./globals.css";const nunito = Nunito({ subsets: ["latin"], variable: "--font-nunito", display: "swap" });export default function RootLayout({ children }: { children: ReactNode }) {  return (    <html lang="en" className={nunito.variable}>      <body className="bg-b5 font-sans text-c2 antialiased">        <PageShell          header={            <SiteHeader              brand={                <Link href="/" className="font-extrabold text-c1 text-lg">                  packs                </Link>              }              links={[                { label: "Public packs", href: "/packs" },                { label: "Docs", href: "/docs" },              ]}            />          }          footer={            <SiteFooter              columns={[{ title: "Help", items: [{ label: "Docs", href: "/docs" }] }]}              finePrint="Not affiliated with osu! or ppy Pty Ltd."            />          }        >          {children}        </PageShell>      </body>    </html>  );}

// src/app/page.tsximport { ButtonLink, Card, PageHeader } from "@haruhimemoe/ui";export default function Home() {  return (    <>      <PageHeader        title="Beatmap packs"        lead="Pick maps, name the pack, share the link."        actions={<ButtonLink href="/new">New pack</ButtonLink>}      />      <Card title="Recent packs" className="mt-8">        Nothing here yet.      </Card>    </>  );}

Import every component from @haruhimemoe/ui, in Server and Client Components alike.

• Client components: CopyButton, Chip, ChipGroup, RangeSlider and FilterPanel, and since 0.4.0 AsyncButton, InlineConfirm, Disclosure, ChoiceChips, RadioGroup, TypeToConfirm and HeaderMenu, and since 0.5.0 Tabs, VisibilitySelect and ReportDisclosure, and since 0.8.0 CommandPalette and CommandPaletteButton, and since 0.14.0 Dialog and ConfirmDialog, and since 0.16.0 MapPreviewButton and MapCopyScope (and the stopMapPreview() function). Each file starts with "use client". They merge their classes with tailwind-merge in the browser, so a page that renders any of them loads tailwind-merge (about 9 KB gzipped), however its header renders.
• SiteHeader and NavLinks are Server Components with a small client part (since 0.2.0; in 0.1.0 NavLinks is a client component). When a nav link can be the current page (a path such as /packs), a client list reads the path to set aria-current. With only external or text-only links, the nav renders on the server alone and nothing in it hydrates. Relative hrefs (#main) skip the client list too, but they render next/link, which hydrates.
• ContentNav (since 0.11.0) reads the path to mark the current page, like NavLinks, but it always hydrates: its class strings are finished (no cx), so it ships no tailwind-merge to the browser. CopyMarkdownButton (since 0.11.0) is the same: finished classes, no tailwind-merge, even though ContentPage (a Server Component) renders it. ContentLayout and ContentPage are Server Components. BrandSwatch (since 0.11.0) is the same again: BrandPage is a Server Component and only its swatches hydrate, with no tailwind-merge.
• CopyField and SegmentedControl (since 0.13.0) are client components you render from your own "use client" file (a form, a toolbar), not ones a server component renders for you: they merge classes with cx like the other client components above.
• MapCard, MapSetCard, MapGroup and MapCover (since 0.16.0) are Server Components; with copyId they render the kit's own internal Copy ID button, a small client file with finished classes (no tailwind-merge), the same pattern as CopyMarkdownButton and BrandSwatch. MapPreviewButton and MapCopyScope are the map display's own client files, for a page that renders them directly.
• Everything else is server-safe: no state, no effects, no browser APIs.

A Server Component can't pass a function to a Client Component. So callback props (onChange, onPressedChange, onClear) have to come from your own "use client" file, like the filters example below. Props that are plain data (CopyButton's text, Chip's pressed) work from a Server Component. Pagination takes a function (hrefFor), but it is a Server Component itself, so that is fine anywhere. Its button mode (onPageChange) is a callback, so render that from a "use client" file.

• Every component takes its element's native props and passes them through (id, aria-*, data-*, event handlers). Each section below names that element. The tables list only the extra props.
• ref is a normal prop (React 19). It goes where the native props go: the outer element for most components, the control (<input>, <select>, <textarea>) for the form fields, and the <button> for CopyButton. On PageShell that is the wrapper <div>, not <main>.
• className is added after the built-in classes and wins on conflict: a class that sets the same property as a built-in one replaces it (merged with tailwind-merge). <Select className="w-auto"> drops the built-in w-full. On DiscordIcon, GitHubIcon and HaruhimeWordmark, className replaces the default size instead.

A pill button. Every native <button> prop. Variants: primary (default), secondary, ghost, and since 0.14.0 danger (white on rose-700, rose-800 on hover) for a confirm that deletes.

Since 0.12.0 a button sits at its content width (w-fit), also in a flex column or a grid cell; pass className="w-full" for a full-width one. At md it is 44px tall on a coarse pointer.

A link that looks like Button. Every next/link prop (href, prefetch, replace, scroll, target, rel...), plus variant and size as on Button.

• A string href with a scheme (https:, mailto:) or starting with // renders a plain <a>, and next/link's own props are dropped. The href is read the way the browser reads it: leading spaces don't count and a backslash counts as a slash, so /\host and \\host are off-site too (since 0.4.0).
• That plain <a> with target="_blank" and no rel gets rel="noreferrer". A rel you pass always wins. Internal links get only the rel you pass.

Since 0.12.0, download (any value but false) renders a plain <a download>: no prefetch of an API route or a large file, no client routing. An external href also renders a plain <a>, with rel="noreferrer" in a new tab.

<ButtonLink href="/api/me/export" download variant="secondary">Download my data</ButtonLink><ButtonLink href="https://osu.ppy.sh" target="_blank">osu!</ButtonLink>

buttonClasses({ variant?, size?, className? }): string returns the Button classes, for elements the components don't cover. Types: ButtonVariant, ButtonSize, ButtonClassOptions.

<summary className={buttonClasses({ variant: "secondary" })}>More</summary>

The osu!-web panel: rounded, b4 background, p-5. Every native <section> prop except title.

The page's one <h1>, with room for a lead line, a meta line and actions. Every native <div> prop except title.

Short status text in one of three tones. Every native <p> prop. Type: NoticeTone.

A status region is only reliably announced when its content changes while it is on the page. A live info or warning notice that mounts with its text already inside ({saved && <Notice live>Saved.</Notice>}) can go unannounced. Keep it mounted and change its children, empty while there is nothing to say:

<Notice live>{saved ? "Saved." : ""}</Notice>

An error notice (role="alert") is announced either way.

A line of text in a tone and a size, instead of hand-written color classes. Every native <p> prop. Types: TextTone, TextSize, TextClassOptions.

textClasses({ tone, size, bold, className }) returns the same classes for an element Text can't be (an <output>, a <time>, a class map). Text is styling only, not a live region: a message that appears after an action still goes in Notice live or a mounted role="status". Error and warning text must say what is wrong in words.

<Text tone="muted">Last updated Oct 4.</Text><Text role="alert" tone="error" bold>That pack key is not valid.</Text><output className={textClasses({ tone: "success" })}>Saved.</output>

Long-form typography for MDX, docs and legal pages. A max-w-3xl <div> that styles the h2, h3, h4, p, a, strong, ul, ol, li, dl, code, pre, hr, table, figures, task lists, footnotes and details elements inside it (h4, dl, figures, task lists, footnotes and details since 0.17.0). Every native <div> prop. A pre scrolls sideways, so give it tabIndex={0} (through your Markdown renderer's components map) so keyboard users can reach the scroll; CSS can't add that.

The first element inside gets no top margin ([&>:first-child]:mt-0, since 0.2.0), so a heading that opens the block sits flush with what's above it instead of taking the h2 or h3 gap. The rule reaches direct children only. If you wrap the content in <section>s, the heading at the top of the first section keeps its margin. Reach one level deeper for that:

<Prose className="[&>:first-child>:first-child]:mt-0">  <section>    <h2>What we store</h2>    <p>Your osu! id and your packs.</p>  </section>  <section>    <h2>How long we keep it</h2>    <p>Until you delete your account.</p>  </section></Prose>

Later sections keep their heading margin, which spaces them apart.

Since 0.17.0. A keyboard key: <kbd> with a small bordered look (rounded border border-b3 bg-b5 font-sans text-c3), shared with the command palette's own shortcut hints. Every native <kbd> prop. kbdClasses is the same classes as a plain string, for a <kbd> (or any element) you build yourself.

<p>Press <Kbd>Ctrl</Kbd>+<Kbd>K</Kbd> to open the palette.</p><span className={kbdClasses}>Esc</span>

It also renders for Markdown's kbd element through mdxComponents, and is exported from @haruhimemoe/ui/mdx for <Kbd>Ctrl</Kbd> directly in .mdx source.

Since 0.4.0. A button (at least 24px tall) that shows and hides a panel below it, with aria-expanded and aria-controls and a ▾ / ▴ arrow. The closed panel stays in the page, hidden, so fields inside keep their values. Every native <div> prop except children, for the wrapper.

Since 0.4.0. A text link: next/link inside the app, a plain <a> off-site (with rel="noreferrer" in a new tab), like ButtonLink. Every next/link prop. Type: TextLinkVariant.

<p>  Scripts can read public packs. <TextLink href="/docs/api">Read the API docs</TextLink>.</p><TextLink href={`/packs/${pack.id}`} variant="plain">{pack.name}</TextLink>

download works the same way (since 0.12.0): <TextLink href="/brand/haruhime-palette.json" download>Download palette (JSON)</TextLink>.

Since 0.4.0. linkClasses({ variant?, className? }): string returns the TextLink classes, for an element that should look like one (a <button> that reads as a link, say). Type: LinkClassOptions. Downloads use TextLink download since 0.12.0.

Since 0.4.0. A small pill for a status or tag ("Unranked", "beta", a count). A <span> with no role, so screen readers read it in line with the text around it. Every native <span> prop. Type: BadgeTone.

Since 0.5.0. A tab list for panels on the same page (use LinkTabs when each tab is its own URL): pill buttons with role="tab" in a role="tablist" named by label. The chosen tab is aria-selected and the only one in the Tab order (the first one when none is chosen). Left and Right move and wrap, Home and End jump to the ends; each picks the tab and focuses it. Controlled. Every native <div> prop except onChange and children, for the tablist. Types: TabItem<T>, TabsProps<T>.

The panels are yours. tabId(prefix, tab) and tabPanelId(prefix, tab) (server-safe) give the ids that tie them together (<prefix>-tab-<tab>, <prefix>-panel-<tab>):

<Tabs label="Editor view" idPrefix="ed" tabs={TABS} value={tab} onChange={setTab} /><div role="tabpanel" id={tabPanelId("ed", tab)} aria-labelledby={tabId("ed", tab)}>...</div>

useMotionAllowed() is true when the visitor allows motion. It is false on the server, during hydration, without matchMedia, and while the visitor asks for reduced motion, and it follows the setting live. Use it for motion JavaScript drives (an autoplay video, a canvas, element.animate()). CSS transitions and animations already stop through the theme, so components don't need it for those.

"use client";import { useMotionAllowed } from "@haruhimemoe/ui";export function Hero() {  const motion = useMotionAllowed();  return motion ? <video autoPlay loop muted playsInline src="/loop.webm" /> : null;}

The list and page layout pieces apps used to build by hand (since 0.13.0). All are Server Components except CopyField and SegmentedControl, which are under Forms.

The list-item box: Card's color and radius at p-3, no heading and no landmark. as picks div (default), li, section, article, form or p; padding is sm (p-3), md (p-4) or lg (p-5). It adds no layout: pass flex flex-col gap-2. A p-0 in className replaces the padding.

<ul className="flex flex-col gap-3">  <Surface as="li" padding="md" className="flex flex-col gap-1">…</Surface></ul>

Surface's classes for an element it doesn't render, such as a next/link tile: surfaceClasses({ padding, className }).

A card that is one click target. CardLink is the link: its after: box covers the nearest positioned ancestor, and its name is only its own text. LinkCard is the surface (p-5, relative, b3 on hover and focus-within) that the cover fills; every other link, button, field and summary inside is lifted above the cover, so they stay clickable without relative z-10. title plus href renders <h3><CardLink /></h3> first (headingLevel changes the level); without them, put a CardLink in your own heading. media renders first, full-bleed, above the padded body.

<LinkCard media={<img src="/brand/repos/ui-banner.svg" alt="" />}>  <h2 className="font-extrabold text-xl"><CardLink href="/libraries/ui">@haruhimemoe/ui</CardLink></h2>  <LinkRow items={links} /></LinkCard>

• One CardLink per card: two would stack two covers.
• The lift sets position: relative on those elements. Something that must overlay another element inside the card stacks by grid area ([grid-area:1/1]), not absolute.
• CardLink works in any relative box outside LinkCard too; pass after:rounded-[10px] when the box is rounded and doesn't clip.
• Use Card for a labelled region and LinkCard for a card that goes somewhere.

A grid of cards as a list: one column on phones, columns 2 (default) or 3 from sm/lg, gap md (default, 16px then 20px) or sm (10px), as ul or ol. It wraps each child in a flex <li>, so cards in a row match height: cards render no <li> of their own.

<CardGrid columns={3}>{templates.map((t) => <TemplateCard key={t.id} template={t} />)}</CardGrid>

Label and value pairs as a <dl>: variant inline (default, a wrapping row), tiles (b4 boxes; on a b4 parent pass className="[&>div]:bg-b3") or grid (2 columns on phones, columns 2, 3 or 4 from sm). Labels are c4 at text-xs, values bold c1 with tabular numbers. Values take any node.

<StatList variant="tiles" items={[{ label: "Maps", value: "12" }, { label: "Avg ★", value: "5.2" }]} />

The "nothing here yet" box: variant dashed (default) or filled, size md (default, centered, p-6) or sm (left, tight), optional title and action. It has no role; announce it with your own live region when it appears after a search.

<EmptyState className="min-h-48">Drop an image here to start.</EmptyState>

A native <progress> with a name and a status line: label (shown unless hideLabel), value (left out for indeterminate) and max (default 1), status in an <output> under the bar that the bar's aria-describedby points at. The output is always mounted, so a status set later is announced.

<Progress label="Download progress" hideLabel value={ready} max={total} status={`${ready} of ${total} sets ready`} />

A wrapping row of text links (a card's GitHub / npm / Changelog, a page's filters): plain without a label, a named <nav> with one. variant accent (default, bold accent links) or quiet (c2, turns c1 on hover). Mark the current item with current: it gets aria-current="page" and an underline, not color alone. Use LinkTabs for pill links that switch a view of the same page family, ContentNav for a section's vertical nav.

<LinkRow label="Changelog filter" items={[{ href: "/changelog", label: "All" }, { href: "/changelog/kind/packages", label: "Packages", current: true }]} />

The h2 under a page's h1: bold c1 at text-xl, scroll-mt-20 for a sticky header. level changes the tag (default 2). detail ("(12)") sits inside the heading's accessible name; actions sit to its right; anchor (needs id) adds a # link named after the heading's text.

<SectionHeading id="recent-packs" anchor detail="(12)" actions={<a href="/packs">See all</a>}>Recent public packs</SectionHeading>

Previous and next links at the end of a page in a series (docs tags, guides): a named nav over a b3 rule. Each link reads "Previous: " or "Next: <title>" to a screen reader; a lone next link sits at the end on its own. Renders nothing with neither link.

<PrevNext label="More tags" prev={{ href: "/docs/tags/b", title: "[b] Bold" }} next={{ href: "/docs/tags/i", title: "[i] Italic" }} />

Inline code with a copy button: copy={false} for the code alone; the button's name is Copy <code> unless copyLabel.

<CodeChip code="bun add @haruhimemoe/ui" />

The fields render a label, the control, an optional hint and an optional error, wired together for screen readers. They are Server Components: you pass the id, so they need no generated ids.

Shared props (type FieldProps), taken by TextInput, Textarea, Select and Checkbox:

className goes on the control itself. Your own aria-describedby is kept after the hint and error ids. Fields are 44px tall with 16px text on a coarse pointer (since 0.12.0).

Every native <input> prop (type, name, value, onChange, placeholder, required...), plus the field props.

<TextInput id="pack-name" label="Name" hint="Shown on the pack page." required />

Every native <textarea> prop, plus the field props. At least min-h-24 tall, resizes vertically.

Every native <select> prop, plus the field props. Pass <option> elements as children.

Every native <input> prop except type (checked, defaultChecked, onChange, name, disabled...), plus the field props. The box is 24px (since 0.8.0; it was the browser's 13px), the label is bold text-c1 and the hint follows it inline after a dot. Clicking anywhere on the row toggles it. The label alone is the accessible name; the hint is the description. An aria-labelledby you pass is added after the label (since 0.4.0; 0.3.0 dropped it).

Since 0.4.0. A native radio group on the Checkbox look: a <fieldset> named by its <legend>, one 24px radio per option with a bold label and an inline hint, then the group's hint and error. Each option's label is its accessible name and its hint its description. Arrow keys move and pick, as native radios do. Every native <fieldset> prop except onChange, children and defaultValue; disabled turns off every radio. Types: RadioOption.

Since 0.4.0. A confirm for something that can't be undone: a <form> whose submit button stays off until the expected text is typed exactly (spaces around it don't count). The field has no autocomplete, autocapitalize or spellcheck. Enter submits once it matches. Children show above the field, to say what the action does. Every native <form> prop except onSubmit.

<TypeToConfirm id="delete-pool" expected={pool.name} submitLabel="Delete this pool" onConfirm={remove} error={error}>  <p>This deletes the pool for everyone who edits it. It can't be undone.</p></TypeToConfirm>

In a dialog, use ConfirmDialog's typeToConfirm (see Which confirm).

Since 0.5.0. How much of a length limit a text uses: "1,234 / 60,000 characters" in c3, then bold rose with ": 1,500 over the limit" once past it (at the limit is not over). You count, so any rule works (a string's length, a BBCode counter). Every native <p> prop except children.

With live (since 0.7.0) an <output> live region inside it announces "1,500 over the limit" when the count goes over and nothing while under, so typing isn't read out number by number.

Since 0.5.0. Who can see something: private, unlisted or public, each with a line that says who that is. As radios (a RadioGroup, every line shown as its option's description) or as a native select (a Select, the picked option's line as the hint). Controlled. Also exported: VISIBILITIES (["private", "unlisted", "public"]), the Visibility type, VisibilityText ({ label: string; hint?: ReactNode }) and VISIBILITY_TEXT, the default words ("Only you can see it.", "Anyone with the link can see it. It isn't listed.", "Anyone can see it, and it's listed.").

<VisibilitySelect  label="Who can see this pool"  value={visibility}  onChange={setVisibility}  text={{ private: { hint: "Only you and your editors." } }}/>

Since 0.5.0. "Report this": a Disclosure holding a reason Textarea (required) and a submit button. onSubmit gets the trimmed reason and says how it went: { ok: true, message? } replaces the form with a role="status" line (your message, like "You already reported it.", or sentMessage), which takes focus, since the button that had it is gone (since 0.7.0; the line is mounted empty from the start, so it is announced); { ok: false, message } shows the message as the field's error and keeps what was typed for a retry. A throw reads as failedMessage. One send at a time. Type: ReportResult.

<ReportDisclosure  summary="Report this template"  maxLength={500}  onSubmit={async (reason) => {    const response = await fetch(`/api/templates/${id}/report`, { method: "POST", body: JSON.stringify({ reason }) });    return response.ok ? { ok: true } : { ok: false, message: "Reporting failed." };  }}/>

fieldClasses(className?: string): string returns the field look (b6 background, b3 border, h1 border plus the theme's 2px h1 outline on focus, rose border when aria-invalid, and the h1 border back when an invalid field has focus; before 0.7.0 the outline was hidden and only the border changed). Use it on a bare control that labels itself:

<select aria-label="Move to" className={fieldClasses("w-auto")}>...</select>

A read-only field to copy from: the value in mono (mono={false} to turn it off), focus selects all of it, then a row with a Copy button and your actions. The label to input gap is 8px. ref, hint, error and hideLabel reach the input; wrapperClassName places the whole field. The Copy button is described by the label, so two fields read "Copy, Pack key" and "Copy, Short link". A copy that depends on something only the browser knows (a share link with window.location.origin) goes in actions as its own CopyButton.

<CopyField label="Pack key" value={packKey} copyLabel="Copy key" copyVariant="primary" copiedMessage="Key copied."  actions={<CopyButton text={shareLink} disabled={!origin} label="Copy share link" />} />

A two to four way view switch drawn like a pill track, built on native radios: Tab lands on the checked one, arrows move and pick. Radios, not links: use LinkTabs when each choice is its own URL, ChoiceChips for a filter among other chips. hideLabel keeps the group named through an sr-only legend; size is sm (24px) or md (default, 32px).

<SegmentedControl label="Preview size" hideLabel size="sm" options={[{ value: "fit", label: "Fit" }, { value: "actual", label: "Actual size" }]} value={scale} onChange={setScale} />

A button that copies text, with the result in an <output> beside it that screen readers announce. Each press clears the message first, so a second copy is announced too. Only the latest press reports: an earlier copy that settles later (behind a permission prompt, say) doesn't overwrite it (since 0.4.0). If the clipboard is missing or refuses (an insecure page, say), it shows the failure message. Every Button prop except onClick and children; className and the native props go on the button.

Previous and next pills around "Page X of Y": links (hrefFor), or since 0.4.0 buttons (onPageChange). Renders nothing when there is one page or none. Every native <nav> prop except children; aria-label defaults to "Pages".

A page or pageCount straight from a URL is safe to pass (since 0.4.0): NaN reads as page 1 (and a NaN count as one page), a page past either end is pulled back inside, and fractions are dropped. Number("abc") shows page 1 with a Next link, and page 99 of 5 shows page 5.

The links use next/link with rel="prev" and rel="next". On the first and last page one link goes away. If it had keyboard focus (Next pressed on page 4 of 5), focus moves to the "Page X of Y" text instead of falling back to the top of the page. Pagination stays a Server Component; that text is a small client component inside it.

In button mode, Previous and Next are <button>s. At the first or last page they stay in place, dimmed, with aria-disabled="true": they keep focus and ignore presses. The status is a polite live region there, so each new page is announced.

<Pagination page={page} pageCount={null} hasNext={data.hasMore} onPageChange={setPage} />

Since 0.4.0. A button that runs an async action and reports how it went in an <output> beside it that screen readers announce, like CopyButton. While it runs, the button keeps focus but ignores presses (aria-disabled). Every Button prop except onClick; the children are its text.

Since 0.4.0. A two-step confirm in the page, no dialog: a trigger button, then the question with a cancel and a confirm button in its place. Opening moves focus to cancel, the safe choice. Cancel or Escape closes it and puts focus back on the trigger, and so does a confirm that resolves. The open confirm is a <fieldset> (a group) named by the question, so screen readers hear the question when focus arrives. Every native <div> prop except children, for the wrapper.

If a confirm removes the item (and the InlineConfirm with it), move focus somewhere sensible yourself, such as the list's heading. For a delete that affects other people or sits in a table cell, use ConfirmDialog (see Which confirm).

Since 0.14.0. A modal base and a confirm built on it. Both are client components: their callbacks come from your own "use client" file.

The bare modal: a native <dialog> that follows open. Opening records what had focus, runs showModal() (the rest of the page goes inert), focuses initialFocus and locks the page's scroll. Closing puts focus back on what opened it, or on returnFocus() when that has left the page, and puts the page's own inline overflow back. Unmounting while open does the same and asks no one. Nothing closes by itself: Escape and a backdrop press call onDismiss, and you set open to false. A backdrop press counts only when it starts and ends on the backdrop, so a text selection dragged out of the dialog never closes it. When the browser closes it itself (a back gesture), onDismiss("browser") tells you to follow. A dialog opened from inside one that closes at the same time (a palette command) sends focus back to that one's opener. It fades in (motion); close is instant, and reduced motion shows it at once. Every native <dialog> prop except open, onCancel and onClose. Name it with aria-label or aria-labelledby.

The <dialog> is the backdrop's hit area: make it cover the viewport and put your panel inside it, or a press on the panel's own padding counts as a backdrop press.

"use client";const [open, setOpen] = useState(false);<Button onClick={() => setOpen(true)}>Preview</Button><Dialog  open={open}  onDismiss={() => setOpen(false)}  aria-labelledby="preview-title"  className="m-0 h-dvh max-h-none w-full max-w-none open:flex">  <div className="m-auto w-[calc(100%-2rem)] max-w-md rounded-xl border border-b3 bg-b6 p-5">    <h2 id="preview-title" className="font-bold text-lg">Template preview</h2>    <Button onClick={() => setOpen(false)}>Close</Button>  </div></Dialog>

A confirm in a modal alertdialog, on Dialog. The title names it and the description describes it. Cancel (ghost) and Confirm sit in a form, so Enter submits. Below sm the buttons go full width with Confirm on top. Focus starts on Cancel, the safe choice, or on the type field with typeToConfirm. While onConfirm runs (once at a time), both buttons keep focus but ignore presses, Confirm shows pendingLabel, and Escape and the backdrop do nothing. When it resolves the dialog closes and focus goes back to the trigger, or to returnFocus() if the trigger is gone. When it throws or rejects the dialog stays open, keeps what was typed, and says failedMessage in an alert. Content renders only while open, so each open starts fresh.

<ConfirmDialog  trigger="Delete this pool"  triggerProps={{ variant: "danger" }}  title={`Delete ${pool.name}?`}  description="This deletes the pool for you and everyone who edits it. It can't be undone."  tone="destructive"  typeToConfirm={pool.name}  confirmLabel="Delete for good"  pendingLabel="Deleting…"  failedMessage={(error) => (error as Error).message}  onConfirm={async () => {    const answer = await deletePool(pool.id);    if (!answer.ok) throw new Error(answer.message);  }}/>

Pick by what is lost and who loses it, then by where the trigger sits.

1. No confirm. The change can be undone in place (an Undo, Ctrl+Z), it only touches an unsaved form, or redoing it costs a click. Never confirm something that has an Undo.
2. InlineConfirm. It can't be undone, touches only your own things, and the consequence fits one short sentence. The trigger sits in a row or toolbar with room to grow.
3. ConfirmDialog. It can't be undone, and it affects other people (shared links, editors, someone else's content), or the consequence needs more than one sentence, or the trigger sits where inline growth breaks the layout (a table cell, a header menu, a palette command).
4. ConfirmDialog with typeToConfirm. It can't be undone and it deletes an account, deletes a thing other people edit, or gives ownership away. Type the account's or the thing's name.
5. TypeToConfirm. Only when the confirm is the whole page, or a step in a flow with nothing else on screen.

Never window.confirm(), and never a hand-built modal: build on Dialog.

Since 0.3.0. The Discord logo as an inline SVG in the current text color. Hidden from screen readers by default (aria-hidden="true"), so put a label on the link around it. Every native <svg> prop except children and viewBox.

The path is Simple Icons' discord.svg at tag 16.32.0 (simple-icons/simple-icons, CC0 1.0). Discord is a trademark of Discord Inc. Its brand guidelines ask for the logo in color, black or white, and not recolored. The icon takes the current text color, so give the element around it one of those (SiteFooter uses white).

The GitHub mark as an inline SVG in the current text color. Hidden from screen readers by default (aria-hidden="true"), so put a label on the link around it. Every native <svg> prop except children and viewBox.

The haruhime.moe wordmark as an inline SVG. It keeps the brand's own white and pink whatever --hue is; under theme-light.css the white becomes c1 ink (--wordmark-ink, since 0.20.0). Every native <svg> prop except children and viewBox.

A plain <a> around a decorative HaruhimeWordmark, dimmed until hovered. Every native <a> prop except children.

The osu! beatmap listing layout: a panel of rows, each with a label on the left and controls on the right. The interactive pieces take callbacks, so render them from a "use client" file:

"use client";import {  ChipGroup,  type ChipOption,  FilterPanel,  FilterRow,  RangeSlider,  type RangeSliderValue,} from "@haruhimemoe/ui";import { useState } from "react";const MODS: ChipOption[] = [  { value: "HD", label: "HD" },  { value: "HR", label: "HR" },  { value: "DT", label: "DT" },];export function PackFilters({ count }: { count: number }) {  const [mods, setMods] = useState<string[]>([]);  const [stars, setStars] = useState<RangeSliderValue>([0, null]);  const active = mods.length > 0 || stars[0] > 0 || stars[1] !== null;  return (    <FilterPanel      title="Filters"      resultCount={`${count} packs`}      active={active}      onClear={() => {        setMods([]);        setStars([0, null]);      }}    >      <FilterRow label="Mods">        <ChipGroup label="Mods" hideLabel options={MODS} value={mods} onChange={setMods} />      </FilterRow>      <FilterRow label="Star rating">        <RangeSlider          label="Star rating"          hideLabel          min={0}          max={10}          step={0.1}          openEnded          value={stars}          onChange={setStars}        />      </FilterRow>    </FilterPanel>  );}

Give the ChipGroup or RangeSlider inside a FilterRow hideLabel. The row's label then shows once, and screen readers hear the row's name once instead of two nested groups with the same name.

A toggle pill: a <button> with aria-pressed, h1 when on. Every native <button> prop except aria-pressed, which pressed sets.

Your own onClick runs first. Call event.preventDefault() in it to skip the toggle.

A labelled row of chips for picking several values (mods, game modes). A <fieldset>; every native <fieldset> prop except onChange and children. disabled turns off every chip.

Since 0.4.0. One choice from a few, as a real radio group drawn as chips (a status or type filter): native radios under one name, so Tab reaches the checked chip and the arrow keys move and pick. Same look as Chip, with the focus ring on the chip. A <fieldset> like ChipGroup, with the same label and hideLabel; every native <fieldset> prop except onChange, children and defaultValue. Type: ChoiceChipOption.

For a two to four way view switch drawn as a pill track, use SegmentedControl.

Two thumbs on one track with an editable box at each end, for star rating, length or BPM. A <fieldset>; every native <fieldset> prop except onChange, children and inputMode. Type: RangeSliderValue ([number, number | null]), so useState<RangeSliderValue> can pass its setter straight in.

The thumbs can't cross. Arrow keys move one step, Page Up and Page Down ten, Home and End as far as the thumb can go. A box commits on blur or Enter, and Escape undoes the typing. An empty low box means min; an empty top box means open (with openEnded) or max. Values that come in out of range or crossed (from a URL, say) are shown clamped, and a NaN or infinite end counts as no limit on that end. When both thumbs sit on one value, dragging moves whichever end can go that way.

One labelled row: the label above the controls on phones, in a w-28 column on the left from sm up. A <fieldset>; every native <fieldset> prop. Server-safe.

Not the same as the fields' hideLabel: inside a FilterRow, a ChipGroup, ChoiceChips or RangeSlider's own hideLabel drops its label entirely, because the row names it instead.

A titled panel of FilterRows with a live result count and a "Clear filters" button. On phones the rows fold behind a button next to the title; from sm up they always show. Every native <section> prop except title.

schema.org structured data in a <script type="application/ld+json">. Every < in the output is escaped, so a string in the data can't close the tag. Every native <script> prop except children, dangerouslySetInnerHTML, type and src (id and nonce pass through).

Since 0.11.0. A content section's side navigation, page grid and search, ports of bb's docs sidebar, layout grid and search. ui has no next-kit or brand dependency: resolve your section's entries (a docs registry, a future blog) into these plain, structural types yourself.

type ContentNavItem = { href: string; title: string; navTitle?: string; badge?: string };type ContentNavGroup = { heading?: string; items: readonly ContentNavItem[] };

ContentSearchItem (ContentNavItem & { description: string; keywords?: readonly string[] }) is exported too, for searchContent, ContentSearch and ContentIndex below.

The index link, then each group of links, the current page marked. A column from lg up; a "Contents" disclosure above it on phones. Finished class strings (no cx).

A link's label is navTitle ?? title, in a line-clamp-2 span so a long title wraps to two lines instead of overflowing the 14rem column; the link's title attribute always holds the full title. The current page's link gets aria-current="page". A badge (e.g. a count) shows beside the label, in font-mono.

For a page's own vertical nav use ContentNav; for a wrapping row of links (a card's GitHub / npm / Changelog, a page's filters) use LinkRow.

The grid: nav in a 14rem column from lg up, the page beside it; one column on phones. A Server Component. nav takes an already-rendered node (usually a <ContentNav>), so this stays section-agnostic. Every native <div> prop; className merges last.

searchContent(items: readonly ContentSearchItem[], query: string): ContentSearchItem[]. Pure and server-safe. A blank (or whitespace-only) query returns every item, in input order. Otherwise query is lowercased and split on spaces; an item matches when every word appears somewhere in its title, navTitle, description, badge or any keywords. Matching items whose title starts with the trimmed query come first; the rest keep their input order.

Port of bb's docs search. A TextInput (id content-search, type="search"), a polite live region with the result count, then ContentIndex over what searchContent found.

The same card grid as ContentSearch (one link per item: title, badge, description), with no search field, for a section with too few entries to bother searching (/legal, a handful of guides). A Server Component. Its tiles use CardGrid gap="sm" and surfaceClasses (since 0.13.0).

Since 0.17.0. An article's table of contents, built from articleData's (or MDX's mdxExports') flat toc: TocItem[]: a sticky column from xl up beside the page, and a phone disclosure above it, both labelled "On this page" (the same column and link classes as ContentNav, through contentNavStyles.ts). A Server Component; every native <nav> prop goes on the wide-screen column (the phone disclosure carries its own nav, so the same props on both would duplicate an id).

Renders nothing when fewer than two items survive maxDepth (a one-heading page needs no toc). A heading whose level jumps more than one step still nests one level at a time (2 then 4 nests once, not twice), and repeated ids keep distinct React keys.

const page = await import(`./posts/${slug}.mdx`); // mdxExports: true<ContentPage title={meta.title} toc={<Toc items={page.toc} />} /* ... */>  <page.default /></ContentPage>

Since 0.11.0. A content section's page: PageHeader (the title and the description as its lead), a meta row (byline, published/updated dates, reading time) with a "Copy as Markdown" button, then the body in Prose, with an optional toc beside it and a footer after it. Optional JSON-LD. A Server Component.

ContentAuthor ({ name: string; userId?: number; href?: string | null; avatarUrl?: string }) names an author; userId links an osu! profile and draws its avatar unless href/avatarUrl say otherwise. Several authors join "A, B and C".

Since 0.11.0. A button that fetches href and copies the response body to the clipboard, reporting the result in an <output> beside it, like CopyButton. Any failure (the fetch rejects, the response isn't ok, or the clipboard refuses) shows the same failure message; it never throws. Its own client file with finished class strings (no cx): ContentPage is a Server Component, and this keeps tailwind-merge out of the browser bundle it ships.

Since 0.11.0. A product's /brand page body. Pass it @haruhimemoe/brand's data as is:

import { brandPageData } from "@haruhimemoe/brand/products";import { BrandPage } from "@haruhimemoe/ui";<BrandPage {...brandPageData("pools")} />;

The props are typed structurally, so ui doesn't depend on brand. Sections, in order, each a Card with an <h2>: Name (name, tagline, how to write it, the site), Logo (each file previewed on a dark b6 or light tile by dark, with a download link; non-image files get the link only), slots.afterLogo, Colors (a BrandSwatch per palette token), slots.afterColors, Type, Do's and don'ts, osu! ("Not affiliated with osu! or ppy. osu! is a trademark of ppy Pty Ltd."), Family ("Part of the haruhime.moe family.", linking familyHref; hidden when it's null, as on haruhime.moe itself), Contact (a mailto: link), slots.end. The headings and the osu! and family lines are the same on every haruhime brand page. A Server Component.

Since 0.11.0. One palette token: a button showing the color, the token and its hex. Clicking copies the hex and reports the result in an <output> beside it, like CopyButton. The color is set inline from the data (style={{ backgroundColor }}), so it doesn't follow --hue. Finished class strings, no tailwind-merge.

Links in the header and footer are data (type SiteLinkItem):

type SiteLinkItem = { label: string; href?: string; note?: string };

Paths use next/link; anything with a scheme (https:, mailto:) or starting with // is a plain <a> (and, since 0.4.0, /\host, \\host or a URL behind leading spaces, which browsers also read as off-site). An item without href shows as plain text. note adds a word beside it in small uppercase letters ({ label: "Sheets", note: "soon" }). The header dims text-only items and shows the note only on them. The footer shows a note beside a link too.

The dark top bar: brand on the left, the nav, and an actions slot on the right. Every native <header> prop except children. A Server Component; the nav list inside is NavLinks.

The link for the current page gets aria-current="page" and lights up. A section link gets aria-current="true" on pages under it (/packs while on /packs/123). / only matches itself.

Only a path inside the app can be the current page. External URLs, relative hrefs (#main, ?page=2) and text-only entries never are. Since 0.2.0, when no link can be, the nav skips the client list. With only external and text-only entries, it renders on the server alone and nothing in it hydrates. A relative href still renders next/link, which hydrates. When a link can be the current page, a small client list marks it. In 0.1.0 the whole nav is a client component, so it always hydrates.

Rendered from a Server Component, SiteHeader and NavLinks merge the nav's classes on the server, so tailwind-merge stays out of the browser (since 0.2.0; in 0.1.0 the nav always brings tailwind-merge to the browser). Rendered inside a Client Component, they merge them in the browser and bring tailwind-merge with them.

Next bundles every client component a route imports, rendered or not. So a page with SiteHeader still downloads the client list's small chunk (mostly next/link), even when the nav rendered on the server alone.

The <ul> of links SiteHeader uses, for building your own header. Put it inside a <nav>. Every native <ul> prop except children. Type: SiteNavAlign. It works in Server and Client Components. Since 0.2.0 it is a Server Component with a small client part (in 0.1.0 it is a client component). From a Server Component it behaves like SiteHeader's nav. Inside a Client Component (a header with a menu toggle, say), it renders in the browser with the rest of that component: it merges its classes there, so tailwind-merge ships in that page's bundle.

Link columns, an extra slot, fine print, the haruhime.moe wordmark, a GitHub icon link and an optional Discord icon link. Every native <footer> prop except children. Type: SiteFooterColumn ({ title: string; items: readonly SiteLinkItem[] }).

HARUHIME_TOOLS (each { id, name, href, blurb }, type HaruhimeTool, ids HaruhimeToolId: "packs" | "pools" | "bb") and haruhimeToolsColumn(options) (the same column as plain data, for a footer you lay out yourself) are exported too. Since 0.6.0. They are the one place outside the wordmark that names the haruhime.moe tools: a tool joins the list when it goes live.

Since 0.4.0. A row of link tabs (Pools / Maps, All / Hidden): a named <nav> with a list of pill links. The current one gets aria-current="page" and a b3 pill (underlined in forced colors mode). These are links, not ARIA tabs, since each loads its own URL. A Server Component: you say which is current. Every native <nav> prop except children. Type: LinkTabItem.

For a plain wrapping row of links instead of pills, use LinkRow. For a view switch with no URL of its own, use SegmentedControl.

Since 0.4.0. The header's account menu: a button (an avatar and a name, say; at least 24px tall) that shows a small panel of links and extra controls such as a sign-out button. It is a disclosure, not an ARIA menu: the button has aria-expanded and aria-controls, and Tab moves through the panel. Escape closes it and puts focus back on the button; a click outside it, a click on one of its links, or focus leaving it closes it too. Every native <div> prop except children, for the wrapper. Type: HeaderMenuItem.

The page frame: a skip link, the header, <main> and the footer, with the footer held to the bottom on short pages. Every native <div> prop; they and ref go on the outer wrapper <div>. Use mainId and mainClassName for <main>, and document.getElementById(mainId) to reach it from script.

Since 0.4.0. Display pieces for beatmaps, mod pools, map lists and (since 0.10.0) players. They take plain values (no osu! API types) and are Server Components.

A star-rating pill colored on osu!'s difficulty spectrum: "★ 5.23" on the rating's color, dark text up to 6.5 and osu!'s pale yellow above, except where neither clears 4.5:1 on the pill (the violet band around 6.5 to 7 stars), which gets white (since 0.7.0). The spectrum is osu!'s own, the same at every --hue, so the pill sets its colors inline. Screen readers hear "5.23 stars" and the label after it. Every native <span> prop except children; a style you pass merges over the colors.

A beatmap's CS, AR, OD, HP, BPM and length as a compact <dl>, in that order. Stats you leave out (or that aren't finite) don't show. CS, AR, OD, HP and BPM are <abbr>s titled with their full names; screen readers get the full name instead of the letters (since 0.7.0). Every native <dl> prop except children. Type: BeatmapStatKey.

A mod pool slot's pill (NM1, HD2, TB), colored by the first two letters: NM sky, HD amber, HR rose, DT and NC violet, FM emerald, TB orange, with dark text. Anything else is a b3 pill. Every native <span> prop; children replace the text. A custom bucket picks its color with color: <ModBadge mod={code} color={PALETTE[entry.color].toLowerCase() as ModBadgeColor} />. className still recolors it (bg-pink-300) when color's fixed list doesn't fit.

Since 0.10.0. osu!-web's user card (the 120px card from the friends list and user tooltips): the profile cover under a dark overlay, the 60px avatar, the country flag, the team flag and the supporter heart, the username, and an optional status row. The whole card links to the osu! profile. Every native <div> prop except children.

It never fetches. Pass a snapshot you keep yourself (from one osu! API lookup, or typed by hand), so a page of cards costs no API calls and hits no rate limits. Leave status out for static data: the card draws no online or offline ring unless told to. Images are plain <img> tags (lazy; the avatar and flags are sized), so the app needs no images.remotePatterns for osu!'s hosts. A cover ending in .gif is hidden when the visitor asks for reduced motion.

<PlayerCard  username="peppy"  userId={2}  countryCode="AU"  coverUrl="https://assets.ppy.sh/user-profile-covers/2/….jpeg"  team={{ name: "mom?", flagUrl: "https://assets.ppy.sh/teams/flag/1/….png" }}  supporter  statusText="osu!"/>

The bottom row is left out when there is no status, text or note; the card keeps its 120px height so cards line up in a grid. A card with a cover gets a b5 overlay at 80%, enough for c2 text at 12px to keep 4.5:1 over a white cover (axe can't check text over an image).

MapCard, MapSetCard, MapGroup, MapCover, MapPreviewButton and MapCopyScope draw one map, a set, a bucket of maps and their covers and preview clips from plain props. None of them fetch. MapCard's map prop takes @haruhimemoe/osu's BeatmapMeta as-is: <MapCard beatmapId={meta.beatmapId} map={meta} /> needs no adapter, since MapData's field names match BeatmapMeta's. An app with different field names writes one small mapping function instead (pools' BuiltMap, say): { beatmapsetId: m.setId, starRating: m.stars, lengthSeconds: m.length, creator: m.setHost, ... }.

<MapCard  beatmapId={meta.beatmapId}  map={meta}  slot={{ label: "NM1" }}  copyId/>

MapCard

One map as a row (packs' slot row, the default) or a card (osu-web's beatmapset panel). Every native <div> prop except children, title and slot (the DOM attribute; slot here is the pool slot pill).

Both layouts sit inside a @container, so a row's actions wrap under the text below a 42rem (@2xl) container width and sit inline from there; a long "Artist - Title" truncates with the full text in the title element's title. MapCover's pixel sizes set each cover's aspect: 400x140 (aspect-[20/7]) for the card background and panel's wide spot, 900x250 (aspect-[18/5]) for a standalone wide cover, square (aspect-square) for the list/cover squares. coverUrl={null} draws no cover square at all (rows line up anyway); leaving it unset with no usable beatmapsetId draws the ♪ placeholder.

MapSetCard

A beatmapset and its difficulties: a header (cover, "Artist - Title" linked to the set, status, badges, mapper, note) over a list of MapDifficultyRows in the order given. Backgrounds apply to the header only.

MapGroup

A bucket of maps: a labelled <section> with a heading (title, optional mod pill, a count or "count of target", a detail), actions beside it, the maps as list items, and empty-slot rows or a summary row. Every native <section> prop except title.

MapCover

A beatmapset's cover as a plain lazy <img> (no next/image, so an app needs no images.remotePatterns for assets.ppy.sh), sized from osu!'s own cover files so nothing shifts while it loads. With no usable set id and no src, it draws a b5 box with a ♪ glyph instead.

MapPreviewButton

A play/stop button for a set's preview clip from b.ppy.sh, filling its parent (MapCard stacks it on the cover square by grid, not absolute). One clip plays per page, at half volume (PREVIEW_VOLUME); a clip stops once no button for its set is mounted, or when ending on its own. stopMapPreview() stops whatever is playing (call it on a route change). Renders nothing for a set id that isn't a positive whole number. Client.

mapCoverUrl(beatmapsetId, size?) and MAP_STATUS_LABELS (ranked, approved, loved, qualified, pending, wip, graveyard, frozen) are the plain helpers MapCard and MapSetCard build on, exported for an app that draws its own covers or status words.

CSP: an app using the map display needs img-src https://assets.ppy.sh and, if it plays previews, media-src https://b.ppy.sh.

Accessibility: every control names its own map (Copy ID is "Copy ID <id>", the preview button is "Play/Stop preview of <song>"); an app adding its own slot actions should name them with the map the same way. Covers are decorative (alt=""); a loading MapCard is aria-busy with visible skeleton bars plus an sr-only "Loading beatmap <id>". Inside a MapCopyScope, only the Copy ID pressed last keeps "Copied."; a nested scope joins its outer one, so a page can wrap one scope around several MapGroups (each already scoped) and still get one "Copied." at a time.

Since 0.9.0. Three subpaths, so an app that never renders Markdown loads none of this: @haruhimemoe/ui/mdx (the React pieces: mdxComponents, CodeBlock, Callout, and since 0.17.0 the article pieces Figure, Steps, Embed, MdxLinkCard, Schedule, Glossary, Term, Kbd), @haruhimemoe/ui/remark (plain functions, no React, for @next/mdx and react-markdown's remarkPlugins), and @haruhimemoe/ui/shiki (opt-in code highlighting). The root @haruhimemoe/ui export adds Toc and Kbd/kbdClasses (0.17.0; see "Basics" and "Content" above).

With @next/mdx:

// next.config.tsimport createMDX from "@next/mdx";const withMDX = createMDX({  extension: /\.mdx?$/,  // Turbopack only takes MDX plugins as module names, not imported functions.  options: { remarkPlugins: ["remark-gfm", "@haruhimemoe/ui/remark"] },});export default withMDX({ pageExtensions: ["ts", "tsx", "md", "mdx"] });

// mdx-components.tsximport { mdxComponents } from "@haruhimemoe/ui/mdx";import "@haruhimemoe/ui/shiki"; // optional: see "Code highlighting" belowexport function useMDXComponents(components) {  return { ...mdxComponents, ...components };}

remark-gfm isn't ui's dependency (pin it yourself); without it @next/mdx has no pipe tables, and a table with no GFM stays a paragraph.

With react-markdown:

import { mdxComponents } from "@haruhimemoe/ui/mdx";import remarkHaruhime from "@haruhimemoe/ui/remark";import remarkGfm from "remark-gfm";import Markdown from "react-markdown";<Markdown components={mdxComponents} remarkPlugins={[remarkGfm, remarkHaruhime]}>  {body}</Markdown>;

mdxComponents must render in a Server Component: CodeBlock (its pre override hands off to) is async, and a client component can't render an async one. A client-side renderer, like a live editor preview, can't use pre from this map; pass your own synchronous override for that case.

If you sanitize the output (rehype-sanitize or your own schema), allow className on code matching /^language-/, dataMeta on code, dataCallout on blockquote, and id on h2/h3: the remark plugin writes these, and mdxComponents reads them back. rehype-sanitize's default clobberPrefix renames those heading ids to user-content-…; pass clobberPrefix: "" (what haruhime.moe uses) to keep the plain id, or live with the prefix and update any hand-written anchor links to match.

The element overrides apps pass to @next/mdx's useMDXComponents or react-markdown's components: { a, blockquote, details, div, h2, h3, h4, img, input, kbd, pre, table } (details, div, h4, img, input, kbd since 0.17.0). Spread it and add your own ({ ...mdxComponents, Example: LiveExample }); your own key of the same name always wins.

An async Server Component: a header bar (the fence's title, or the language name, or "Code") with a copy button, over a <pre role="group" tabIndex={0}> of lines. Every native <div> prop goes on the wrapper except code, lang, title and highlight.

In MDX, pass these through the fence's meta string instead of writing CodeBlock by hand: ```ts title="pool.ts" {2,4-5}. parseCodeMeta reads title="…" or title='…' and {1,3-5} ranges (anything else is ignored, and it never throws); the language comes from the fence's own tag.

shiki is an optional peer dependency: apps that never render code don't install it, and ui's only runtime dependency stays tailwind-merge. An app that renders code:

bun add shiki

// in the module that renders code: mdx-components.tsx, or next to your react-markdown callimport "@haruhimemoe/ui/shiki";

That import is a side effect: it registers a Shiki core highlighter (shiki/core with the no-WASM JS regex engine, loaded through dynamic import()) under @haruhimemoe/ui/mdx's CodeBlock. The registration lives on globalThis for the whole process, not per module graph, but it only exists once the import has actually run: put it in the module that renders code (mdx-components.tsx, which reaches every MDX page, or directly beside your react-markdown renderer) so it runs before CodeBlock does. package.json's sideEffects lists ./dist/shiki.js, so bundlers don't drop the bare import; Turbopack resolves even a dynamic import("shiki/core") at build time, which is why highlighting is a separate subpath instead of CodeBlock importing it unconditionally.

Without the import, CodeBlock renders plain, unstyled lines, and in development it logs one console.warn per process ("code blocks aren't highlighted…"). A highlighter that fails to load (a missing package, a broken build) falls back the same way, warned once.

Tokens render as <span style={{ color: "var(--shiki-token-…)" }}>, no injected Shiki HTML, through --shiki-* custom properties in theme.css (see "Setup" above for loading it). They follow --hue like the rest of the palette: --shiki-foreground and --shiki-background are c2/b6; -punctuation is c3 and -comment is c4, the palette tokens as-is; -keyword and -link are hsl(var(--hue) 100% 78%), the palette's own hue with no offset; -string, -string-expression, -constant, -function and -parameter are each calc(var(--hue) + N), a hue-offset HSL value. Every one stays at or above 4.5:1 against both b6 (the block's background) and b4 (a highlighted line's tint) at every integer hue. keyword and link get their own fixed lightness instead of reusing h1: h1's default (76%) drops to 4.33:1 against b4 at hue 240, and a --h1-l override written for other text shouldn't silently recolor code too.

A labelled aside: a left-border panel (role="note") with an icon and a bold label, usable directly in MDX or rendered by mdxComponents' blockquote override.

GitHub-style callout syntax works through the remark plugin: a blockquote whose first paragraph starts with [!NOTE], [!TIP], [!WARNING] (case-insensitive; GitHub's [!IMPORTANT] maps to tip, [!CAUTION] to warning) becomes a Callout of that type, the marker stripped:

> [!NOTE]> Packs are deleted after 90 days of no edits.

Or write <Callout type="tip"> directly in an .mdx file.

Plain functions (no React), for remarkPlugins. Default export remarkHaruhime(options?) runs all three transforms below in order and is what Turbopack needs by module name: remarkPlugins: ["@haruhimemoe/ui/remark"]. Named exports remarkCodeMeta, remarkCallouts and remarkHeadingIds run one each, for react-markdown's array form or a custom pipeline.

slugify(text) and createSlugger() are also exported: lowercase, Unicode-aware (letters, marks, digits and underscores from any script survive; everything else but whitespace and hyphens is dropped), spaces to hyphens, repeats suffixed -1, -2 like GitHub's own heading anchors. @haruhimemoe/ui/mdx re-exports slugify for apps that build their own heading links.

Since 0.17.0. ContentPage grew authors, published, readingMinutes, toc and footer for a blog post or a long guide, on top of the docs/legal page props it already had:

// next.config.ts: Turbopack only takes MDX plugins by module name, and `mdxExports`// (a boolean) is the one option that's safe to pass as a [name, options] tuple.options: { remarkPlugins: ["remark-gfm", ["@haruhimemoe/ui/remark", { mdxExports: true }]] }