@hearthsound/design 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hearthsound contributors
+
+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.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @hearthsound/design
 
-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.
+The design language of Hearthsound: tokens, fonts, icons and component styles. It ships
+plain CSS, so it works in any framework and needs no build step of its own.
+
+## Install
+
+```sh
+npm install @hearthsound/design
+```
+
+Import the stylesheet once per application:
+
+```js
+import '@hearthsound/design/index.css';
+```
+
+`index.css` pulls in `css/tokens.css`, `css/base.css` and every component stylesheet, in
+that order. Individual files can be imported instead, for example
+`@hearthsound/design/css/tokens.css`.
+
+## Schemes: System, Light and Dark
+
+The light scheme is the default. Dark follows the operating system unless the page
+chooses otherwise. The choice is a `data-scheme` attribute, which may sit on `<html>` or
+on any subtree:
+
+| Attribute | Result |
+|---|---|
+| none | System: dark under `prefers-color-scheme: dark`, light otherwise |
+| `data-scheme="light"` | Light, even on a dark system |
+| `data-scheme="dark"` | Dark, even on a light system |
+
+```html
+<!-- System -->
+<html>
+<!-- Force light -->
+<html data-scheme="light">
+<!-- Force dark -->
+<html data-scheme="dark">
+```
+
+There is one fixed brand accent; there is no accent attribute.
+
+## Class naming
+
+Components use BEM-like `hs-` classes:
+
+- block: `hs-<component>` (for example `hs-button`, `hs-dialog`);
+- element: `hs-<component>__<part>` (for example `hs-dialog__title`);
+- modifier: `hs-<component>--<modifier>` (for example `hs-button--suggested`);
+- utilities: the type scale (`hs-display`, `hs-title-1` to `hs-title-4`, `hs-heading`,
+  `hs-body`, `hs-caption`), `hs-link`, `hs-visually-hidden` and `hs-icon`.
+
+State is expressed with real pseudo-classes and ARIA attributes, never helper classes:
+`:hover`, `:focus-visible`, `:disabled`, `[aria-disabled="true"]`, `[aria-pressed="true"]`,
+`[aria-selected="true"]`, `[aria-current]`, `[aria-busy="true"]`, `[aria-invalid="true"]`
+and `[aria-expanded="true"]`. Focus is the approved tint-and-lift treatment shown on
+`:focus-visible` only.
+
+Style with the shipped tokens, not raw values:
+
+```css
+.my-shell {
+  background: var(--hs-view-bg);
+  color: var(--hs-fg);
+  padding: var(--hs-space-5);
+  border-radius: var(--hs-radius-card);
+}
+```
+
+Tokens cover colour, type, spacing, density, radii, elevation, focus, motion and artwork.
+`css/tokens.css` is the complete list; the light values are the `:root` base and dark
+values apply through the media query and the `data-scheme` attribute.
+
+## Fonts
+
+Three OFL faces ship in `fonts/` and are declared in `css/base.css`:
+`Geist` (body, `--hs-font-body`), `Bricolage Grotesque` (display, `--hs-font-display`) and
+`Geist Mono` (machine text, `--hs-font-mono`, ligatures off). The font files are loaded
+relative to the stylesheet, so no path configuration is needed.
+
+## Icons
+
+The approved icon set ships as individual SVGs in `icons/` and as a generated sprite in
+`dist/icons.svg`. Each source name in the manifest maps to a file name and symbol id by
+replacing `/` with `-`:
+
+- manifest `adwaita/play` -> `icons/adwaita-play.svg` -> symbol `#adwaita-play`;
+- manifest `custom/upload` -> `icons/custom-upload.svg` -> symbol `#custom-upload`.
+
+Use the sprite with the `hs-icon` base class:
+
+```js
+import sprite from '@hearthsound/design/icons.svg?url';
+import { iconNames } from '@hearthsound/design/icons'; // string[]
+```
+
+```html
+<svg class="hs-icon" aria-hidden="true">
+  <use href="/path/to/icons.svg#adwaita-play"></use>
+</svg>
+```
+
+`hs-icon` is 16 px by default and inherits `currentColor`; set `--hs-icon-size` to resize
+it. `@hearthsound/design/icons` exports `iconNames` and, in TypeScript, the `IconName`
+union type. Give a labelled icon `role="img"` and an accessible name; otherwise mark it
+`aria-hidden="true"`.
+
+## Identity
+
+The approved identity files ship unchanged:
+
+- `identity/mark/mark-light.svg`, `mark-dark.svg`: the full-colour mark for each scheme.
+- `identity/mark/mark-symbolic.svg`: the one-colour mark in `currentColor`.
+- `identity/icons/app-icon-light.svg`, `app-icon-dark.svg`: 128 px masters.
+- `identity/icons/app-icon-{light,dark}-{16,32,180,192,512}.png`: exported sizes.
+- `identity/icons/favicon.svg`: one file that switches with `prefers-color-scheme`.
+
+Use the full-colour mark only on its own scheme, keep a quarter of the mark's height as
+clear space, and never rebuild a one-colour mark from the full-colour file: use
+`mark-symbolic.svg`. Licence details are in `THIRD-PARTY.md`.
+
+## Development
+
+```sh
+npm run build      # writes dist/icons.svg, dist/icons.js and dist/icons.d.ts
+npm run check      # build, then verify tokens, imports, ASCII, fonts and icon refs
+npm run specimen   # build, then write the unpublished specimen/index.html
+```
+
+`specimen/index.html` shows every component in every state, light and dark side by side.
+It is a development reference and is not published.

package/THIRD-PARTY.md

@@ -0,0 +1,46 @@
+# Third-party notices
+
+The package itself is MIT licensed; see `LICENSE`.
+
+## Fonts
+
+### Geist and Geist Mono
+
+Copyright (c) 2023 Vercel, in collaboration with basement.studio.
+
+Licensed under the SIL Open Font License, Version 1.1. The full licence text ships as
+`fonts/OFL-Geist.txt`.
+
+Files: `fonts/geist-var.woff2`, `fonts/geist-mono.woff2`.
+
+### Bricolage Grotesque
+
+Copyright 2022 The Bricolage Grotesque Project Authors
+(https://github.com/ateliertriay/bricolage).
+
+Licensed under the SIL Open Font License, Version 1.1. The full licence text ships as
+`fonts/OFL-BricolageGrotesque.txt`.
+
+File: `fonts/bricolage-var.woff2`.
+
+## Icons
+
+### Adwaita symbolic icons
+
+Copyright the GNOME Project. The icons are licensed under the terms of either the GNU
+LGPL v3 or the Creative Commons Attribution-Share Alike 3.0 United States License. The
+full notice ships as `icons/LICENSE`. When attributing the artwork, "GNOME Project" is
+enough; see http://www.gnome.org.
+
+Files: every `icons/adwaita-*.svg`.
+
+### Custom icons derived from Adwaita
+
+`icons/custom-like-outline.svg`, `icons/custom-dislike-outline.svg`,
+`icons/custom-dislike.svg`, `icons/custom-upload.svg` and `icons/custom-unknown.svg` are
+drawn from Adwaita shapes and carry the same licence and attribution as the Adwaita set.
+
+## Identity
+
+The Hearthsound mark, app icons and favicon are original work of the Hearthsound
+contributors and are covered by the package's MIT licence.

package/css/base.css

@@ -0,0 +1,245 @@
+/*
+ * @hearthsound/design - base
+ *
+ * Fonts, reset, body typography, the type-scale classes (foundations.md 2.2),
+ * the focus indicator carrier, the icon base class and reduced motion.
+ * Component looks live in css/components/; this file only owns the page frame.
+ */
+
+/* f01, f01b, f02, B09 - the three approved faces, shipped in fonts/. */
+@font-face {
+  font-family: 'Geist';
+  src: url('../fonts/geist-var.woff2') format('woff2');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Bricolage Grotesque';
+  src: url('../fonts/bricolage-var.woff2') format('woff2');
+  font-weight: 200 800;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Geist Mono';
+  src: url('../fonts/geist-mono.woff2') format('woff2');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+
+/* ------------------------------------------------------------------ */
+/* Reset                                                              */
+/* ------------------------------------------------------------------ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  background: var(--hs-view-bg);
+  color: var(--hs-fg);
+  font-family: var(--hs-font-body);
+  font-size: var(--hs-type-body-size);
+  font-weight: var(--hs-type-body-weight);
+  line-height: var(--hs-type-body-lh);
+  letter-spacing: var(--hs-type-body-track);
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+/* f02 - the mono face is shown with ligatures off. */
+code,
+kbd,
+pre,
+samp {
+  font-family: var(--hs-font-mono);
+  font-variant-ligatures: none;
+}
+
+/* ------------------------------------------------------------------ */
+/* Type scale (f03, l07)                                              */
+/* ------------------------------------------------------------------ */
+
+.hs-display {
+  font-family: var(--hs-font-display);
+  font-size: var(--hs-type-display-size);
+  font-weight: var(--hs-type-display-weight);
+  line-height: var(--hs-type-display-lh);
+  letter-spacing: var(--hs-type-display-track);
+}
+
+.hs-title-1 {
+  font-family: var(--hs-font-display);
+  font-size: var(--hs-type-title-1-size);
+  font-weight: var(--hs-type-title-1-weight);
+  line-height: var(--hs-type-title-1-lh);
+  letter-spacing: var(--hs-type-title-1-track);
+}
+
+.hs-title-2 {
+  font-family: var(--hs-font-display);
+  font-size: var(--hs-type-title-2-size);
+  font-weight: var(--hs-type-title-2-weight);
+  line-height: var(--hs-type-title-2-lh);
+  letter-spacing: var(--hs-type-title-2-track);
+}
+
+.hs-title-3 {
+  font-family: var(--hs-font-display);
+  font-size: var(--hs-type-title-3-size);
+  font-weight: var(--hs-type-title-3-weight);
+  line-height: var(--hs-type-title-3-lh);
+  letter-spacing: var(--hs-type-title-3-track);
+}
+
+.hs-title-4 {
+  font-family: var(--hs-font-display);
+  font-size: var(--hs-type-title-4-size);
+  font-weight: var(--hs-type-title-4-weight);
+  line-height: var(--hs-type-title-4-lh);
+  letter-spacing: var(--hs-type-title-4-track);
+}
+
+.hs-heading {
+  font-family: var(--hs-font-display);
+  font-size: var(--hs-type-heading-size);
+  font-weight: var(--hs-type-heading-weight);
+  line-height: var(--hs-type-heading-lh);
+  letter-spacing: var(--hs-type-heading-track);
+}
+
+.hs-body {
+  font-family: var(--hs-font-body);
+  font-size: var(--hs-type-body-size);
+  font-weight: var(--hs-type-body-weight);
+  line-height: var(--hs-type-body-lh);
+  letter-spacing: var(--hs-type-body-track);
+}
+
+.hs-caption {
+  font-family: var(--hs-font-body);
+  font-size: var(--hs-type-caption-size);
+  font-weight: var(--hs-type-caption-weight);
+  line-height: var(--hs-type-caption-lh);
+  letter-spacing: var(--hs-type-caption-track);
+}
+
+/* ------------------------------------------------------------------ */
+/* Links (f06-r4)                                                     */
+/* ------------------------------------------------------------------ */
+
+a.link,
+.hs-link {
+  color: var(--hs-accent-text);
+  font-weight: 500;
+  text-decoration-line: underline;
+  text-decoration-color: var(--hs-accent-bg);
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+}
+
+/* f06-r4 - light raises the underline to 3 px at a 3 px offset. */
+@media (prefers-color-scheme: light) {
+  :root:not([data-scheme='dark']) :where(a.link, .hs-link) {
+    text-decoration-thickness: 3px;
+    text-underline-offset: 3px;
+  }
+}
+
+[data-scheme='light'] a.link,
+[data-scheme='light'] .hs-link {
+  text-decoration-thickness: 3px;
+  text-underline-offset: 3px;
+}
+
+[data-scheme='dark'] a.link,
+[data-scheme='dark'] .hs-link {
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+}
+
+/* f13-r3 - links take a tint background on keyboard focus. */
+a.link:focus-visible,
+.hs-link:focus-visible {
+  outline: none;
+  background: var(--hs-accent-tint);
+  color: var(--hs-accent-text);
+}
+
+/* ------------------------------------------------------------------ */
+/* Focus                                                              */
+/* ------------------------------------------------------------------ */
+
+/*
+ * f13-r3, k01b, k03f: focus is the tint-and-lift treatment, never a ring,
+ * outline, underline, bar or dot. Each component owns its exact focus rule;
+ * this reset removes the user-agent ring so no component has to repeat it.
+ * Text-type fields keep --hs-control-tone and show focus through the caret
+ * (k03f); filled buttons deepen their fill (k01b).
+ */
+:focus-visible {
+  outline: none;
+}
+
+/* ------------------------------------------------------------------ */
+/* Utilities                                                          */
+/* ------------------------------------------------------------------ */
+
+.hs-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+/*
+ * f12 A - every icon is an inline SVG using the shipped sprite. Size it with
+ * --hs-icon-size (16 px default); colour is inherited through currentColor.
+ */
+.hs-icon {
+  --hs-icon-size: 16px;
+  display: inline-block;
+  flex: none;
+  width: var(--hs-icon-size);
+  height: var(--hs-icon-size);
+  fill: currentColor;
+  vertical-align: middle;
+}
+
+/* ------------------------------------------------------------------ */
+/* Reduced motion (f14b-r1)                                           */
+/* ------------------------------------------------------------------ */
+
+/*
+ * The duration tokens are overridden to 0ms in tokens.css. Scrolling is
+ * immediate as well. Components set their own animation fallbacks (the
+ * spinner is the recorded k09-rm exception).
+ */
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    scroll-behavior: auto;
+  }
+}

package/css/components/admin.css

@@ -0,0 +1,257 @@
+/*
+ * Admin area composition (l10, p05, p24-r3, p26, p26b).
+ * The admin pages reuse the k28 row groups (list.css) and the k13 cards (card.css);
+ * this file adds only the admin-specific pieces: the Overview grid, the instance-dialog
+ * import-root rows, the plugin permission list, the storage bar with its legend, and
+ * the acquisition row spacing.
+ *
+ * plugin-approval-interim: the Install confirmation (340 px dialog with the permission
+ * list, Cancel and a suggested Install) and the File-tab permission list are built but
+ * stay switched off until the core reports permissions for uninstalled plugins. Until
+ * then no permission list shows before install. No CSS state is added for the switch.
+ */
+
+/* ------------------------------------------------------------------ */
+/* l10 B - Overview: a card grid; the cards themselves are card.css    */
+/* ------------------------------------------------------------------ */
+
+.hs-admin-overview {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 16px;
+}
+
+@media (max-width: 720px) {
+  .hs-admin-overview {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* p05 - instance dialog import-root rows                              */
+/* ------------------------------------------------------------------ */
+
+/* A grey group inside the Files section of the 640 px instance dialog. */
+.hs-import-roots {
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--hs-radius-card);
+  overflow: hidden;
+  background: var(--hs-group-bg);
+  box-shadow: var(--hs-group-shadow);
+}
+
+.hs-import-root {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  box-sizing: border-box;
+}
+
+.hs-import-roots .hs-import-root + .hs-import-root {
+  box-shadow: inset 0 1px 0 var(--hs-separator);
+}
+
+.hs-import-roots > .hs-setting-row {
+  box-shadow: inset 0 1px 0 var(--hs-separator);
+}
+
+.hs-import-root__id {
+  flex: none;
+  width: 110px;
+}
+
+.hs-import-root__path {
+  flex: 1;
+  min-width: 0;
+}
+
+.hs-import-root__path .hs-field__value {
+  font: 12.5px var(--hs-font-mono);
+}
+
+.hs-import-root__mode {
+  flex: none;
+  width: 96px;
+}
+
+.hs-import-roots__hint {
+  margin: 6px 0 0;
+  color: var(--hs-fg-muted);
+  font-size: 12.5px;
+}
+
+/* Phones: the path takes the full first line; Id and Mode share the second. */
+@media (max-width: 720px) {
+  .hs-import-root {
+    flex-wrap: wrap;
+  }
+
+  .hs-import-root__path {
+    flex-basis: 100%;
+    order: -1;
+  }
+
+  .hs-import-root__id,
+  .hs-import-root__mode {
+    width: calc(50% - 4px);
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* p24-r3 - plugin permission list                                     */
+/* ------------------------------------------------------------------ */
+
+.hs-permission-list {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  margin-top: 6px;
+}
+
+.hs-permission-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 13px;
+}
+
+.hs-permission-row__scope {
+  flex: none;
+  min-width: 64px;
+  font: 12px var(--hs-font-mono);
+  color: var(--hs-fg);
+}
+
+.hs-permission-row__detail {
+  flex: 1;
+  min-width: 0;
+  color: var(--hs-fg-muted);
+}
+
+.hs-permission-row .hs-pill {
+  flex: none;
+  margin-left: auto;
+}
+
+@media (max-width: 720px) {
+  .hs-permission-row {
+    flex-wrap: wrap;
+    row-gap: 2px;
+  }
+
+  .hs-permission-row__detail {
+    flex-basis: 100%;
+    order: 3;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* p26 - storage usage bar and legend                                  */
+/* ------------------------------------------------------------------ */
+
+.hs-storage-usage {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  max-width: 760px;
+  padding: 18px;
+  border-radius: var(--hs-radius-card);
+  background: var(--hs-group-bg);
+  box-shadow: var(--hs-group-shadow);
+}
+
+.hs-storage-bar {
+  display: flex;
+  height: 14px;
+  border-radius: var(--hs-radius-full);
+  overflow: hidden;
+  background: color-mix(in srgb, var(--hs-fg) 12%, transparent);
+}
+
+.hs-storage-bar > i {
+  display: block;
+  height: 100%;
+}
+
+.hs-storage-legend {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(170px, 1fr));
+  gap: 12px;
+}
+
+.hs-storage-legend__item {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+}
+
+.hs-storage-legend__swatch {
+  flex: none;
+  width: 12px;
+  height: 12px;
+  margin-top: 3px;
+  border-radius: 3px;
+}
+
+.hs-storage-legend__text {
+  display: flex;
+  flex-direction: column;
+}
+
+.hs-storage-pinned {
+  margin: 0;
+  color: var(--hs-fg-muted);
+  font-size: 13px;
+}
+
+/* p26: Library acid, Cache acid at 55% over the view, Folders muted, the rest free. */
+.hs-storage-bar__library,
+.hs-storage-legend__swatch--library {
+  background: var(--hs-accent-bg);
+}
+
+.hs-storage-bar__cache,
+.hs-storage-legend__swatch--cache {
+  background: color-mix(in srgb, var(--hs-accent-bg) 55%, var(--hs-view-bg));
+}
+
+.hs-storage-bar__folders,
+.hs-storage-legend__swatch--folders {
+  background: var(--hs-fg-muted);
+}
+
+.hs-storage-bar__free,
+.hs-storage-legend__swatch--free {
+  background: color-mix(in srgb, var(--hs-fg) 12%, transparent);
+}
+
+/* ------------------------------------------------------------------ */
+/* p26b - acquisition rows                                             */
+/* ------------------------------------------------------------------ */
+
+.hs-setting-row--acquisition {
+  align-items: flex-start;
+  padding-top: 12px;
+  padding-bottom: 12px;
+}
+
+.hs-setting-row--acquisition .hs-setting-row__text {
+  gap: 3px;
+}
+
+.hs-setting-row--acquisition .hs-setting-row__subtitle {
+  font-size: 13px;
+}
+
+.hs-setting-row--acquisition .hs-pill {
+  flex: none;
+}
+
+/* Phones: the summary wraps and the menu stays a flat icon button. */
+@media (max-width: 720px) {
+  .hs-setting-row--acquisition .hs-setting-row__subtitle {
+    white-space: normal;
+  }
+}