# 8-BIT NES — component system NES arcade CRT, dark-only, modern-crisp. Cross-framework by design. ## Install Reusable across every project in the studio — install it into any repo, no build step. ```bash # from npm — always the current release pnpm add 8bit-nes # or straight from GitHub (a tag is a valid spec too) pnpm add github:TuTranMVP/8bit-components#v0.16.0 ``` ```js // once, at app entry: import "8bit-nes/all.css"; // tokens + base + components import "8bit-nes"; // registers web components ``` Or granular: `8bit-nes/tokens.css`, `8bit-nes/base.css`, `8bit-nes/components.css`, `8bit-nes/elements.js`. The `exports` map keeps every entry addressable; `sideEffects` is declared so bundlers keep the CSS and the custom-element registration. > **Zero build, zero runtime deps.** It ships plain CSS + one ES module, so it drops into a > Vite/Nuxt/Next app, a plain HTML page, or another design-system package all the same. ## CDN / no build No bundler? Link the **minified, single-file** build — the three `@import`s are inlined, so it's one request instead of four. This is the whole recommended ``, tuned for a cold visit (copy it verbatim — every line earns its place): ```html ``` Why it's shaped like that: - **Pin the version.** A pinned `@x.y.z` URL is immutable — jsDelivr serves it `max-age=31536000, immutable`, so a repeat visit costs zero requests. A bare `/npm/8bit-nes/all.min.css` is a *mutable* alias: it revalidates every 7 days and costs a redirect hop on the first hit. Bump the number to upgrade; nothing silently changes underneath a shipped page. A `@0.7` range is the middle ground (patches auto-adopt, still cached a week). - **Preload only the two fonts above the fold.** `nes-sans-var.woff2` (body) and `nes-mono-400.woff2` (chrome/labels). The 700-weight mono is left to `font-display: swap`. The preload `href` must match the CSS-resolved URL *character for character* — same version, same path — or the browser downloads each font twice. - **`integrity` + `crossorigin`.** A pinned URL trusts the CDN not to swap the file; a hash doesn't have to. Digests for every shipped asset (both minified entries, the granular CSS, the fonts, the RAG artifacts) live in [`sri.json`](sri.json), generated from the build by `scripts/gen-sri.mjs` and published at [`/sri.json`](https://tutranmvp.github.io/8bit-components/sri.json) — read it, don't retype it: ```js const sri = await (await fetch("https://tutranmvp.github.io/8bit-components/sri.json")).json(); sri.files["all.min.css"]; // "sha384-…" · sri.cdn is the matching pinned base URL ``` The hashes above belong to the version pinned above. They change with every release — regenerate (`pnpm gen:sri`) or re-fetch `sri.json` when you bump, or the browser will (correctly) refuse the file. - **Fonts don't need a separate request budget.** The whole system is 4 files: 75 kB CSS + 79 kB ESM + 2 woff2 (both subset with `unicode-range`), all Brotli'd by the CDN. ` ``` ### Vue 3.3+ / 3.5 (Vite) — verified **1.** Install: `pnpm add 8bit-nes` **2.** Tell the Vue compiler that `` are custom elements (required, or Vue errors "failed to resolve component"): ```ts // vite.config.ts import vue from '@vitejs/plugin-vue' export default { plugins: [vue({ template: { compilerOptions: { isCustomElement: (t) => t.startsWith('nes-') } } })], } ``` **3.** Import the CSS + register the elements **once** at the app entry: ```ts // src/main.ts import '8bit-nes/all.css' // tokens + base + components import '8bit-nes' // registers every (side-effect) ``` > Vite auto-bundles the three woff2 fonts (the CSS references them with relative `url()`) — no font config. **4.** Use classes + `` in any `.vue`. Custom events bubble as `CustomEvent` — read `event.detail`: ```vue ``` No two-way `v-model` on ``; bind via `@nes:change="v = $event.detail.value"`. Inside `` the controls keep a hidden `` and submit with zero wiring. **Nuxt 3** — `customElements` needs the browser, so register in a **client** plugin: ```ts // nuxt.config.ts export default defineNuxtConfig({ css: ['8bit-nes/all.css'], vue: { compilerOptions: { isCustomElement: (t) => t.startsWith('nes-') } }, }) // plugins/8bit.client.ts import '8bit-nes' ``` ### React 19 No wrapper needed — React 19 passes props and listens to custom-element events natively. ```jsx import './tokens.css'; import './base.css'; import './components.css'; import './elements.js';

console.log(e.detail.correct)} /> ``` (React < 19: use a small `ref` wrapper for the `nes:answer` event.) ## Web components API ```html

STAGE 1 · title ...body...

``` ```html

…

``` ### Form module Native where it can be (Checkbox/Radio groups are a `.control-group` fieldset; ColorPicker is ``; Date/Time are themed native inputs). Stateful controls are `` that each keep a hidden ``, so they **submit inside any form with zero wiring**: ```html Email *

``` Also: `` (stepper), `` (star input), `` (drop zone), ``, `` (free-text combobox). Custom events bubble: `nes:change`, `nes:submit`, `nes:invalid`, `nes:complete`. JS helpers (named exports): `store`, `bleep(seq)`, `SFX`, `setMute/isMuted`, `grantXP(n, el)`, `floatXP(el, text)`, `toast(msg, { accent, timeout })`. ## Extend New component → add a recipe in `components.css`, add a token in `tokens.css` if needed. Keep the Do/Don't: square 90° surfaces everywhere, buttons included (never a radius or chamfer), hard shadow not blur, smooth `--ease` easing (transform/opacity), one accent per block, dark text on solid accents, everything via token. Full guidance in [DESIGN.md](DESIGN.md).