8-bit-vibez

8-bit-vibez

A PICO-8 inspired Lit web component library with a subtle 8-bit aesthetic — hard corners, pixel-art shadows, stepped animations, and arcade UI primitives. Framework-agnostic custom elements that work in React, Vue, plain HTML, or any other stack.

Live Showcase · Storybook

---

Design Philosophy

The 8-bit character comes from geometry and motion, not from maxing out the decorative font everywhere:

• border-radius: 0 — hard corners only
• 2px 2px 0 color hard shadows — depth cue, not cartoon weight
• steps(N) CSS transitions — frame-based state changes, not smooth eases
• Pixel font (--font-pixel) reserved for short labels, scores, and headings — ≥16px
• Body copy and interactive controls use JetBrains Mono (--font-body)
• PICO-8 color palette, tuned to pass WCAG 2.1 AA contrast requirements

---

Components

Sprint 1 — Form Controls

Sprint 2 — Feedback & Status

Sprint 3 — Layout Primitives

Sprint 4 — Arcade & RPG Specials

All form components are form-associated custom elements — they participate in native <form> submit and FormData without any wrapper.

---

Install

npm install 8-bit-vibez lit

<!-- Plain HTML / vanilla JS -->
<script type="module">
  import '8-bit-vibez'
</script>
<link rel="stylesheet" href="node_modules/8-bit-vibez/src/styles/tokens.css">
<pixel-button>PRESS START</pixel-button>

// Bundler (Vite, webpack, etc.)
import '8-bit-vibez'           // registers all 25 elements
import '8-bit-vibez/styles'   // CSS design tokens

// Named imports for tree-shaking
import { PixelButton, PixelDialogBox } from '8-bit-vibez'

// React 19 — custom elements work in JSX natively
import '8-bit-vibez'
import '8-bit-vibez/styles'

<pixel-button variant="primary">START GAME</pixel-button>

---

Running Locally

npm install
npm run dev         # showcase on localhost:5173
npm run storybook   # component docs on localhost:6007

Requires Node 18+.

---

Design Tokens

All visual properties are driven by CSS custom properties in src/styles/tokens.css. These pierce Shadow DOM natively — override them at :root to theme all components at once:

:root {
  /* Colors — PICO-8 palette */
  --bg:      #0d0d1a;
  --bg-2:    #1d2b53;
  --green:   #00e436;
  --blue:    #29adff;
  --yellow:  #ffec27;
  --red:     #ff004d;

  /* Typography */
  --font-pixel: 'Dogica', 'Press Start 2P', monospace;  /* decorative */
  --font-body:  'JetBrains Mono', 'Courier New', monospace;

  /* Shape — no border-radius in 8-bit art */
  --radius: 0px;

  /* Motion — stepped feel */
  --ease-step: steps(4);
}

---

Accessibility

• WCAG 2.1 AA color contrast throughout (PICO-8 colors tuned for dark backgrounds)
• prefers-reduced-motion: all CSS animations disabled; pixel-typewriter reveals full text instantly; pixel-sprite freezes on frame 0; pixel-scanline hides entirely
• Full keyboard navigation on all interactive components
• role="meter" on pixel-life, role="progressbar" on pixel-progress, role="tablist" on pixel-tabs, role="dialog" on pixel-dialog
• aria-live="polite" on pixel-score and pixel-status
• Disabled state uses filter: opacity(0.4) instead of opacity so WCAG 1.4.3 inactive-UI exemption is correctly recognized by accessibility tools

Known Gaps

• pixel-typewriter prefers-reduced-motion fallback shows full text immediately ✓ but the aria-live region on inline usage may be verbose — wrap in a semantically appropriate container
• pixel-map canvas content has role="img" with a label, but tile-level detail is not exposed to AT (by design — visual decoration)
• pixel-scanline is purely decorative and aria-hidden — no AT impact

---

Roadmap

• pixel-dialog — full inert attribute propagation to sibling elements
• pixel-life / pixel-score — aria-live polite announcements on value change
• Unit tests (@web/test-runner + @open-wc/testing)
• Changelog (changeset)
• pixel-audio — pixel-style audio player with frequency visualizer
• pixel-inventory — grid-based item slot system
• pixel-minimap — live canvas minimap

---

License

MIT