Griotwave UI

griotwave-ui on npm.

Stories told around a fire at night. Black is the dark. Bloom is the embers. Glass is the smoke catching firelight. Stagger is the cadence of the storyteller's voice.

A visual language for the digital griot. React UI primitives plus the canonical token system — distilled from the Griotwave visual-language doc and worn by every tool in Gavin's workshop.

This repo is three things at once:

1. A showcase site (griotwave.dev) — a single-page tour through the language, every chapter and every register.
2. A publishable component library (griotwave-ui) — the primitives that power the showcase, ready for consumption by other tools in the suite.
3. A Storybook — every primitive, foundation, and chapter rendered next to its label, with live theme switching between Group 01 (Ember Bloom) and Group 02 (Industrial Instrument).

Install (consumers)

npm install griotwave-ui

// app.tsx — once at the entry, side-effect import the styles
import "griotwave-ui/styles.css";

import { Wrap, Ambient, Section, Card, GlowingButton } from "griotwave-ui";

export default function App() {
  return (
    <>
      <Ambient />
      <Wrap>
        <Section
          eyebrow="01 — The Voice"
          title="Speak it."
          subtitle="A digital griot needs a voice consistent across every place the story lands."
        >
          <Card>
            <GlowingButton glowColor="#10B985">Tend the bloom</GlowingButton>
          </Card>
        </Section>
      </Wrap>
    </>
  );
}

The compiled stylesheet declares all tokens on :root — --voice, --echo, --whisper, --footstep, --ghost for type, the canvas ladder (--void → --smoke), the eleven embers, the easing curves (--tale, --song, --drum), the radius scale, the blur stack, and the depth shadows.

Public surface

| Export | Role | |---|---| | Wrap | Centered max-width container — 1200px, 80px vertical / 32px horizontal | | Ambient | The three-blob radial light, fixed beneath every content layer | | Section | Eyebrow + title + subtitle + content — the chapter wrapper | | Card | The frosted-glass surface — five-line CSS recipe | | Footer | Three-line stamp at the foot of the workshop | | HubCard | Pointer-tracking ember card with click ripple — for tool grids | | ExperimentsGrid | Auto-fit grid for showcase tiles | | GlowingButton | Ember-bloom button — glowColor picks the ember | | ShinyButton | The restrained sibling — rim-light only, no halo |

You can also import the bare token sheet without the global reset:

import "griotwave-ui/tokens.css";

Scripts

| Command | What it does | |---|---| | npm run dev | Runs the showcase site (Vite dev server, port 5173) | | npm run build | Builds the showcase to dist/ | | npm run preview | Previews the production showcase build | | npm run build:lib | Builds the library to dist-lib/ (Vite library mode + tsc declarations) | | npm run build:types | Just emits type declarations | | npm run storybook | Runs Storybook dev server on port 6006 | | npm run build-storybook | Builds Storybook static site to storybook-static/ | | npm run lint | ESLint |

The two-register system

Griotwave is a library of groups, not a fixed style. The master language remixes across them.

• Group 01 — Ember Bloom — pure black canvas, flat or frosted glass, three-layer bloom, fadeUp + sibling stagger. Color is light. Default register; use for tools that tell a story.
• Group 02 — Industrial Instrument — tactile dashboards with the discipline of a measurement device. Medium 8–12px radii, tinted off-white type, restrained motion. Color is structure. Use for anything load-bearing.

Storybook ships with a theme switcher in the toolbar that toggles between the two registers so you can see the same component change posture.

Reserved channels — never decorative

• anomaly #F472B6 (pink) — exceptions, missing data
• danger #DF0505 (red) — destructive/irreversible actions only
• beacon #FF0033 (neon crimson) — broadcast tools

Voice

Use commit, earned, discipline, register, affordance, cadence, totem, the workshop. Avoid modern, clean, sleek, fresh, leverage, utilize, simple, easy, just. Mix sentence lengths — long sentences for the explanation, short sentences for the verdict.

Repo layout

src/
├── lib/                  # public package surface — barrel + side-effect CSS
├── components/           # primitives shipped via griotwave-ui
│   ├── *.stories.tsx     # Storybook stories, colocated
│   └── ui/               # internal components (NOT exported)
├── sections/             # showcase-only sections (NOT exported)
├── styles/               # tokens.css + global.css
└── stories/              # cross-cutting stories (Foundations, Welcome, Showcase)

.storybook/               # Storybook 9 config — Griotwave-themed manager
vite.config.ts            # showcase dev/build
vite.lib.config.ts        # library mode build
tsconfig.lib.json         # declaration emit for the library

Install (contributors)

npm install --legacy-peer-deps

The --legacy-peer-deps flag is required while Storybook 9 catches up to Vite 8's peer range. Both work fine together at runtime.

License

MIT — see LICENSE.