@frontpanel/css 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dulan Katukurundage
+
+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,101 @@
-# Temporary Holding Version
+# @frontpanel/css
 
-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.
+An early-2000s hardware skin in plain CSS, for building device front panels in the browser:
+liquid-chrome bezels, gel buttons, molded caps, LCD glass and LEDs. Two skins, Chrome Silver and
+Gunmetal Night, follow the system setting. Tokens are `--fp-*` and classes `.fp-*`, with an
+optional Tailwind 4 entry.
+
+The UI kit behind [WhatsTheNextChord](https://whatsthenextchord.com).
+
+**[Documentation](https://dulandev.github.io/frontpanel/)**: guides, live demos, and every
+component, class and token.
+
+> `0.x`: the class and token names may still change between minor versions. Pin the version.
+
+## Install
+
+```bash
+npm install @frontpanel/css
+```
+
+## Use it
+
+Plain CSS, everything in `@layer frontpanel`, so your own unlayered styles win:
+
+```css
+@import "@frontpanel/css/index.css";  /* tokens and .fp-* classes */
+@import "@frontpanel/css/fonts.css";  /* optional: the bundled display and LCD fonts */
+@import "@frontpanel/css/page.css";   /* optional: website pieces around a device */
+@import "@frontpanel/css/base.css";   /* optional: page defaults */
+```
+
+Tailwind 4, where the tokens join the theme (`bg-fp-shell`, `text-fp-ink`, `font-fp-lcd`) and the
+classes become utilities, so variants such as `lg:fp-module` work:
+
+```css
+@import "tailwindcss";
+@import "@frontpanel/css/tailwind.css";
+@import "@frontpanel/css/fonts.css";          /* optional */
+@import "@frontpanel/css/tailwind-page.css";  /* optional */
+@import "@frontpanel/css/tailwind-base.css";  /* optional, and with no layer() */
+```
+
+`tailwind-base.css` puts the page defaults in Tailwind's `base` layer itself. Importing `base.css`
+with `layer(base)` would nest them in a layer of their own, where preflight beats them.
+
+From TypeScript, import the file (`import '@frontpanel/css/index.css'`) rather than the bare
+package name, which a type checker reads as a module without types.
+
+## Entries
+
+| File | Holds | Global side effects |
+| --- | --- | --- |
+| `index.css` | `tokens.css` and `components.css` | None |
+| `tokens.css` | The `--fp-*` colour and font tokens for both skins | None |
+| `components.css` | The `.fp-*` classes | None |
+| `fonts.css` | `@font-face` for Michroma and VT323 (latin, woff2) | None until used |
+| `page.css` | Website pieces: `fp-field`, the phone bottom sheet (`fp-sheet-panel`, `fp-sheet-*`) | None |
+| `base.css` | Page defaults: skin colours and UI font on the root, focus ring, selection | Yes, opt-in |
+| `tailwind.css`, `tailwind-page.css`, `tailwind-base.css` | The same, for Tailwind 4 | As above |
+
+## Skins
+
+Chrome Silver is the default and Gunmetal Night follows a dark system setting. Force either on
+any element, including the root, with `data-fp-skin="silver"` or `data-fp-skin="gunmetal"`. Every
+text pairing passes WCAG AA in both.
+
+## Layout and input
+
+A device can scale as a whole or reflow its modules at your breakpoints: the classes carry no
+viewport breakpoints. Controls are 44 px by default and 36 px under a precise pointer
+(`pointer: fine`). Each interactive class has its own focus ring.
+
+## Motion
+
+Nothing resets motion globally. Each class that moves (the LCD redraw, the LED's double blink,
+the press of a button) handles `prefers-reduced-motion` itself. Under reduced motion the phone
+sheet (`fp-sheet-*`) doesn't slide and its transition lasts 1 ms rather than 0, so a
+`transitionend` listener still hears it finish.
+
+## Fonts
+
+`fonts.css` loads Michroma (silkscreen labels and titles) and VT323 (LCD text) from its own
+`fonts/` folder, and your bundler serves them from wherever it puts them. Without it, the tokens
+fall back to Arial Black and Courier New. Tahoma is the UI face, from the system.
+
+To preload the fonts, they need URLs that don't change between builds. Copy `fonts/` into your
+public folder at build time and write the two `@font-face` rules yourself, pointing at those
+URLs, in place of `fonts.css`. The file names (`michroma-latin-400.woff2`,
+`vt323-latin-400.woff2`) stay the same across releases; a rename would be a breaking change.
+
+## Browser support
+
+The plain CSS uses native CSS nesting, so it needs Chrome and Edge 112, Firefox 117 or Safari
+16.5 (Baseline 2023) or later. Everything else it uses is older: cascade layers, `:where()`,
+`color-mix()`, `dvh` and the `translate` property. The Tailwind entry follows Tailwind 4's own
+support, since Tailwind compiles the nesting away.
+
+## Licence
+
+MIT. The bundled Michroma and VT323 fonts are under the SIL Open Font License; their licence texts
+ship in `fonts/`.

package/base.css

@@ -0,0 +1,41 @@
+/* Generated by scripts/build.ts from src/. Do not edit; edit the source and run `pnpm build`. */
+@layer frontpanel {
+  /*
+   * Page defaults, part of the opt-in page extra: for a page that is mostly a device, or a website
+   * around one. They style elements outside .fp-* classes, so nothing else in the package does this.
+   *
+   * Generated into two entries:
+   * - base.css, in @layer frontpanel: `@import "@frontpanel/css/base.css";` after index.css.
+   * - tailwind-base.css, straight in Tailwind's base layer so they follow preflight and its
+   *   utilities still win: `@import "@frontpanel/css/tailwind-base.css";` after tailwindcss,
+   *   with no layer().
+   */
+  /* The page wears the skin. Native controls and scrollbars follow it, forced or not. */
+  :root {
+    color-scheme: var(--fp-scheme);
+    background-color: var(--fp-color-backdrop);
+    color: var(--fp-color-ink);
+    font-family: var(--fp-font-ui);
+    -webkit-text-size-adjust: 100%;
+  }
+
+  body {
+    margin: 0;
+    min-height: 100dvh;
+  }
+
+  /*
+   * Everything else that takes focus gets the controls' ring: solid, with a glow outside it, since
+   * the glow alone fails non-text contrast on light chrome.
+   */
+  :focus-visible {
+    outline: 2px solid var(--fp-color-focus-ring);
+    outline-offset: 2px;
+    filter: drop-shadow(0 0 3px var(--fp-color-focus));
+  }
+
+  ::selection {
+    background: var(--fp-color-gel);
+    color: var(--fp-color-gel-ink);
+  }
+}