@mystravil/hardpoint 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Hardpoint follows semantic versioning. Before 1.0.0, a breaking change raises the minor version.
+
+## 0.1.0 (2026-11-11)
+
+The first public release. It needs Svelte 5.57 or newer.
+
+- **Components** (Svelte 5 on Bits UI):
+  - Actions and forms: Button, TextField, NativeSelect, Select, Combobox, Checkbox, CheckboxGroup, Switch.
+  - Overlays: Dialog (centred, bottom sheet or full screen), Popover, the Menu family, Tooltip with TooltipGroup, and Toaster with `toast()`.
+  - Navigation: AppShell (header, bottom bar or drawer, rail or sidebar), Tabs, Steps, Pagination.
+  - Data and display: Table, KeyValueList, Stat, Tag, Timeline, MediaFrame with MediaImage, Disclosure.
+  - Feedback: Progress, Spinner, Skeleton, LoadRegion, EmptyState, ErrorState.
+- **Motion** (`@mystravil/hardpoint/motion`): `<Motion tier>` and `useMotion()`, the overlay transitions `pop`, `sheet`, `fade` and `drawer`, and timing tokens for every duration. Quiet motion is the default; expressive effects run only inside `<Motion tier="expressive">` and never under reduced motion.
+- **CSS**, framework-free: `fonts.css` (Geist, Geist Mono and Geist Pixel Square with size-matched fallback faces), `tokens.css` and `base.css`.
+- **Themes**: dark by default; light through `data-theme="light"` on `<html>`, or `data-theme="system"` to follow the device.
+- **Phones**: 44 px touch targets on coarse pointers, 16 px inputs, bottom sheets on compact widths that stay above the on-screen keyboard, and safe-area insets.

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 MYSTRAVIL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The fonts in src/lib/fonts (shipped as dist/fonts) are not covered by this
+licence. Geist, Geist Mono and Geist Pixel Square are licensed under the SIL
+Open Font License 1.1; see OFL.txt and OFL-geist-pixel.txt beside them.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Hardpoint
+
+Hardpoint is a Svelte 5 design system on [Bits UI](https://www.bits-ui.com/). Its look and motion come from Dan Neuenhaus's MONOLITH reel, adapted for ordinary apps: AMOLED black, titanium ink, the Geist type family, square solid blocks for actions and tags, banded tables of mono data, and expressive motion only where an app asks for it. Bits UI supplies the behaviour and accessibility; Hardpoint supplies the look and the motion.
+
+It works on desktop and on phones: 44 px touch targets on coarse pointers, 16 px inputs, bottom sheets on compact widths that stay above the on-screen keyboard, and safe-area insets. Dark is the default theme, and a light theme is built in. Status colours (red, yellow, green) mean status only; no hue is a brand colour.
+
+The package imports nothing from SvelteKit, so plain Svelte apps can use it. The three CSS files are framework-free, so apps without Svelte can use the tokens and base styles.
+
+## Components
+
+- Actions and forms: `Button`, `TextField`, `NativeSelect`, `Select`, `Combobox`, `Checkbox`, `CheckboxGroup`, `Switch`.
+- Overlays: `Dialog` (centred, bottom sheet or full screen), `Popover`, `Menu` with `MenuItem`, `MenuCheckboxItem`, `MenuRadioGroup`, `MenuRadioItem`, `MenuGroup` and `MenuSeparator`, `Tooltip` with `TooltipGroup`, and `Toaster` with `toast()`.
+- Navigation: `AppShell` (header, bottom bar or drawer, rail or sidebar), `Tabs`, `Steps`, `Pagination`.
+- Data and display: `Table`, `KeyValueList`, `Stat`, `Tag`, `Timeline`, `MediaFrame` with `MediaImage`, `Disclosure`.
+- Feedback: `Progress`, `Spinner`, `Skeleton`, `LoadRegion`, `EmptyState`, `ErrorState`.
+
+The source repository has a showcase app with a docs page for each component, the foundations, the motion tokens and a specimen app.
+
+## Install
+
+```sh
+npm install @mystravil/hardpoint
+```
+
+Svelte 5.57 or newer is a peer dependency. Bits UI comes with the package.
+
+## Use
+
+```js
+import '@mystravil/hardpoint/fonts.css';
+import '@mystravil/hardpoint/tokens.css';
+import '@mystravil/hardpoint/base.css';
+
+// Svelte components
+import { Button, Dialog, Table, Pagination, TextField, toast } from '@mystravil/hardpoint';
+// Motion: <Motion tier="expressive"> for infrequent moments, and the overlay transitions
+import { Motion, useMotion, pop, sheet, fade, drawer } from '@mystravil/hardpoint/motion';
+```
+
+Skip `fonts.css` if the app already serves Geist.
+
+The theme is an attribute on `<html>`: `data-theme="light"`, `"dark"` or `"system"` (follows the device). Without it the theme is dark. Set it before first paint, and set `<meta name="theme-color">` to the canvas colour, `#000000` for dark and `#f7f5f0` for light.
+
+## Docs
+
+The design docs are in the source repository's `docs/` folder, which is private: `BRIEF.md` is the spec, with every decision and its reason; `ux-research.md` holds the UI/UX research and standards behind the app and phone rules; `elements-da3.md`, `measurements-da3.md` and `reference/da3/` measure the reference reel. `CHANGELOG.md` in the package lists the changes in each version.
+
+## Develop
+
+```sh
+npm install
+npm run dev      # showcase app in src/routes
+npm run check    # svelte-check, and no SvelteKit imports in src/lib
+npm run build    # showcase build, then svelte-package and publint into dist/
+npm run audit    # targets, overflow, 16px inputs, contrast on every route at four viewports, dark and light
+npm run shot -- /foundations shots/f.png --serve                       # screenshot with console-error check
+npm run shot -- /foundations shots/f-phone.png --w 390 --h 844 --touch --full --serve
+```
+
+`src/lib` is the library. `src/routes` is the showcase.
+
+## Licence
+
+The code is MIT licensed (`LICENSE`). The fonts are not: Geist, Geist Mono and Geist Pixel Square ship in `dist/fonts` under the SIL Open Font License 1.1 (`OFL.txt`, `OFL-geist-pixel.txt`).

package/dist/base.css

@@ -0,0 +1,346 @@
+/* Hardpoint base. Framework-free like tokens.css: element defaults use
+   :where() so any app rule overrides them, and helpers carry an hp- prefix.
+   Import after tokens.css. */
+
+/* ---- Document ---------------------------------------------------------- */
+
+*,
+*::before,
+*::after {
+	box-sizing: border-box;
+}
+
+/* hidden="until-found" (Disclosure's closed content) stays out of this rule:
+   the browser hides it with content-visibility so find in page can search it. */
+[hidden]:not([hidden='until-found' i]) {
+	display: none !important;
+}
+
+html {
+	-webkit-text-size-adjust: 100%;
+	text-size-adjust: 100%;
+	scrollbar-color: var(--border) transparent;
+}
+
+body {
+	margin: 0;
+	background: var(--canvas);
+	color: var(--text);
+	font-family: var(--sans);
+	font-size: var(--type-body);
+	font-weight: 400;
+	line-height: 1.5;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+	text-rendering: optimizeLegibility;
+}
+
+:where(h1, h2, h3, h4, h5, h6, p, figure, blockquote, dl, dd) {
+	margin: 0;
+}
+
+:where(h1, h2, h3, h4, h5, h6) {
+	font-size: inherit;
+	font-weight: 500;
+}
+
+/* Line breaks. Reading text never ends on a lone word; headings and title
+   roles balance their lines (this rule comes second, so a title set on a
+   <p> balances). The longhand leaves the wrap mode alone, so a nowrap or
+   truncating parent still holds; browsers without it wrap as before. */
+:where(p, li, dd, blockquote, figcaption) {
+	text-wrap-style: pretty;
+}
+
+:where(h1, h2, h3, h4, h5, h6, .hp-page-title, .hp-section-title, .hp-display) {
+	text-wrap-style: balance;
+}
+
+/* Reading measure: a paragraph stops at --measure, about 70 characters. */
+:where(p) {
+	max-width: var(--measure);
+}
+
+/* Square corners everywhere: no cuts, no radii, also on native controls. */
+:where(button, input, select, textarea) {
+	font: inherit;
+	letter-spacing: inherit;
+	color: inherit;
+	border-radius: 0;
+}
+
+:where(button, a, input, select, textarea, summary, label) {
+	touch-action: manipulation;
+}
+
+:where(img, svg, video, canvas) {
+	display: block;
+	max-width: 100%;
+}
+
+:where(a) {
+	color: inherit;
+	text-decoration-thickness: 1px;
+	text-underline-offset: 0.2em;
+}
+
+:where(code, kbd, samp, pre) {
+	font-family: var(--mono);
+}
+
+/* Inline code in running text moves to the next line whole, so a token
+   never splits at a hyphen or a space (--control-height, aria-label).
+   One wider than the line wraps inside its own box: at a hyphen or space
+   first, anywhere if it must, so it never overflows at 320px. Only direct
+   children of reading blocks: an atomic box in a truncating cell (a table
+   dd) would vanish whole into the ellipsis, and a link's underline does
+   not reach into one. */
+:where(p, li, blockquote, figcaption) > :where(code, kbd, samp) {
+	display: inline-block;
+	overflow-wrap: anywhere;
+}
+
+::selection {
+	background: var(--text);
+	color: var(--canvas);
+}
+
+/* ---- Focus ------------------------------------------------------------- */
+
+/* A 2px titanium contour 4px outside the control, square like everything
+   else. Selection never looks like this: selection is an edge marker and a
+   tint. */
+:where(a, button, input, select, textarea, summary, [tabindex]):focus-visible {
+	outline: 2px solid var(--focus);
+	outline-offset: 4px;
+}
+
+/* For rows and items clipped by a scroll container: draw the contour inside. */
+.hp-focus-inset:focus-visible {
+	outline-offset: -2px;
+}
+
+/* ---- Type roles -------------------------------------------------------- */
+
+/* Tracked caps for short fixed labels: buttons, tabs, tags, column headers,
+   field labels, key-value labels. Never for headings, list items, messages or
+   user data. */
+.hp-label {
+	font-family: var(--sans);
+	font-size: var(--type-label);
+	font-weight: 500;
+	line-height: 16px;
+	letter-spacing: var(--label-tracking);
+	text-transform: var(--label-transform);
+}
+
+.hp-caption {
+	font-size: var(--type-caption);
+	line-height: 18px;
+}
+
+/* Dense UI on fine pointers. Phones keep 16px body text. */
+.hp-dense {
+	font-size: var(--type-body);
+	line-height: 24px;
+}
+
+@media (pointer: fine) {
+	.hp-dense {
+		font-size: var(--type-dense);
+		line-height: 20px;
+	}
+}
+
+.hp-body {
+	font-size: var(--type-body);
+	line-height: 24px;
+}
+
+.hp-section-title {
+	font-size: var(--type-section);
+	font-weight: 500;
+	line-height: 28px;
+	letter-spacing: -0.01em;
+}
+
+.hp-page-title {
+	font-size: var(--type-page);
+	font-weight: 500;
+	line-height: 1.25;
+	letter-spacing: -0.015em;
+}
+
+/* The view title in the shell header: a fixed string the app defines, so it
+   takes tracked caps (20px, 16px on compact). */
+.hp-view-title {
+	font-family: var(--sans);
+	font-size: var(--type-view);
+	font-weight: 500;
+	line-height: 24px;
+	letter-spacing: var(--label-tracking);
+	text-transform: var(--label-transform);
+}
+
+/* One per view, and only for the subject: an identifier (add .hp-mono) or a
+   key figure. Names a user wrote stay at the page-title size. */
+.hp-display {
+	font-size: var(--type-display);
+	font-weight: 500;
+	line-height: round(up, 1.1em, 1px);
+	letter-spacing: -0.02em;
+	font-variant-numeric: tabular-nums;
+}
+
+/* Identifiers, hashes, timestamps, code. */
+.hp-mono {
+	font-family: var(--mono);
+}
+
+/* Numbers in Geist that line up and do not change width as they tick. */
+.hp-num {
+	font-variant-numeric: tabular-nums;
+}
+
+/* Geist Pixel Square: the wordmark and at most one short fixed display line
+   per screen. Never labels, values, body text, page titles or user data.
+   Its module lands on whole pixels only if its top edge does too: do not
+   centre it in a box whose free space is odd. */
+.hp-pixel {
+	font-family: var(--pixel);
+	font-size: var(--type-pixel);
+	font-weight: 400;
+	line-height: var(--type-pixel-leading);
+	letter-spacing: 0;
+}
+
+.hp-pixel-lg {
+	font-family: var(--pixel);
+	font-size: var(--type-pixel-lg);
+	font-weight: 400;
+	line-height: var(--type-pixel-lg-leading);
+	letter-spacing: 0;
+}
+
+/* ---- Wells ------------------------------------------------------------- */
+
+/* The input box: a black well with a 3:1 boundary, never a filled block,
+   because a filled select reads as a button (BRIEF, visual rule 2). Text
+   is 16px at every width, or iOS zooms on focus. Native selects, rich
+   select triggers and text fields share it. line-height: normal makes the
+   line box the glyph box, which the well centres: a text field already
+   centres its text that way, and with the inherited 24px line a select or
+   a trigger set its text 1px higher at every pixel ratio. */
+.hp-well {
+	appearance: none;
+	box-sizing: border-box;
+	height: var(--control-height);
+	padding: 0 var(--space-3);
+	border: 1px solid var(--border-control);
+	border-radius: 0;
+	background-color: var(--canvas);
+	color: var(--text);
+	font-family: var(--sans);
+	font-size: var(--type-body);
+	line-height: normal;
+	text-overflow: ellipsis;
+	transition: background-color var(--dur-hover) var(--settle);
+}
+
+/* A chevron at the end of a select's well. Wrap the well in
+   <span class="hp-well-chevron">: the chevron is the wrapper's ::after,
+   because a <select> draws no pseudo-elements and a background image cannot
+   rotate. It turns to point up while the list is open, with the list's own
+   timing: --dur-pop opening, --dur-pop-exit closing. A rich select's trigger
+   says it is open with aria-expanded; a native select matches :open where
+   the browser supports it (Chromium 133+). The wrapper sets no width; the
+   component sizes it. */
+.hp-well-chevron {
+	position: relative;
+	display: block;
+}
+.hp-well-chevron > .hp-well {
+	padding-right: var(--space-10);
+}
+.hp-well-chevron::after {
+	content: '';
+	position: absolute;
+	top: 50%;
+	/* The well's 1px border, plus the inset a background image had. */
+	right: calc(var(--space-3) + 1px);
+	width: 16px;
+	height: 16px;
+	margin-top: -8px;
+	background-color: var(--muted);
+	mask: var(--select-chevron) center / 16px 16px no-repeat;
+	pointer-events: none;
+	transition: transform var(--dur-pop-exit) var(--settle);
+}
+.hp-well-chevron:has(> [aria-expanded='true'])::after {
+	transform: rotate(180deg);
+	transition-duration: var(--dur-pop);
+}
+/* Its own rule: a browser without :open drops only this one. */
+.hp-well-chevron:has(> :open)::after {
+	transform: rotate(180deg);
+	transition-duration: var(--dur-pop);
+}
+@media (prefers-reduced-motion: reduce) {
+	.hp-well-chevron::after {
+		transition: none;
+	}
+}
+@media (hover: hover) and (pointer: fine) {
+	.hp-well:hover:not(:disabled, [aria-disabled='true']) {
+		background-color: var(--surface-hover);
+	}
+}
+/* Disabled: muted text and the quieter --border, as on a disabled outlined
+   button. Chromium also sets a disabled <select> to 70% opacity; cancelled,
+   so a native and a rich select look the same when disabled. */
+.hp-well:disabled,
+.hp-well[aria-disabled='true'] {
+	border-color: var(--border);
+	color: var(--muted);
+	cursor: not-allowed;
+	opacity: 1;
+}
+
+/* ---- Expressive entrance ---------------------------------------------- */
+
+/* Stagger (motion rule 7): a component that renders its first items in the
+   expressive tier adds .hp-enter and sets --i to the item's index. Items
+   from the sixth on share the sixth's delay. Only on first appearance:
+   never on items added later by filtering, sorting or paging. */
+.hp-enter {
+	animation: hp-enter var(--dur-enter) var(--settle) both;
+	animation-delay: calc(min(var(--i, 0), 5) * var(--stagger-step));
+}
+
+@keyframes hp-enter {
+	from {
+		opacity: 0;
+		transform: translateY(4px);
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.hp-enter {
+		animation: none;
+	}
+}
+
+/* ---- Utilities --------------------------------------------------------- */
+
+/* Hidden from sight, kept in the accessibility tree. */
+.hp-visually-hidden {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	margin: -1px;
+	padding: 0;
+	overflow: hidden;
+	clip-path: inset(50%);
+	white-space: nowrap;
+	border: 0;
+}