performative-ui

performative-ui is a React component library that packages up every visual trope of the modern AI-startup landing page: token streams, ASCII heroes, glowing gradient buttons, mock IDE panels, and waitlist forms with a rotating social-proof counter. Each component is typed, themeable via CSS custom properties, and ships with a headless hook (useTypewriter, useTokenStream, useCounter, useAsciiField) for teams that want the animation logic without the prebuilt markup. The joke is in the framing, the components themselves are production-usable pieces for building real marketing pages fast.

The library is intentionally narrow in scope: no build step configuration, no design tokens to wire up beyond a single stylesheet import, and no dependencies beyond React itself. It targets teams shipping a landing page who want the current aesthetic of AI-product marketing without hand-rolling gradient text, aurora backgrounds, or a fake streaming-token effect from scratch.

What You Get

• About 30 typed React components covering hero sections, animated backgrounds (Aurora, NodeGraphBackground, FloatingSparkles), chat/conversation UI (ChatBubble, TokenStream, ChatFAB), pricing and waitlist components, and social-proof widgets (LogoMarquee, StatCounter, CommunityBadge)
• Four headless hooks (useTypewriter, useCounter, useTokenStream, useAsciiField) that expose the animation logic independently of any bundled markup, for teams building custom UI on top
• A single styles.css file with all component styles namespaced under .pui-*, themeable light/dark via CSS custom properties and a data-theme attribute
• Full TypeScript types for every component’s props, exported alongside each component from the public barrel
• A polymorphic Button component (as prop) supporting five variants and Radix-style ref forwarding for rendering as an anchor or routed link

Common Use Cases

• Standing up an AI-product landing page quickly with pre-styled hero, pricing, and waitlist sections
• Adding a fake streaming-response or typing-indicator effect to a marketing demo without writing the animation logic from scratch
• Building a component style guide or internal marketing kit that needs consistent gradient/glow treatments across pages
• Prototyping a SaaS landing page for design review before committing to a bespoke design system

Under The Hood

Architecture: The library is a flat, single-package React component set with no internal module boundaries beyond components/, hooks/, and utils/. Every component is exported from one barrel file, src/index.ts, which also side-effect-imports styles.css so consumers get all styling from a single import 'performative-ui'. Components are self-contained: they import cn() for class composition and occasionally reference each other directly (e.g. Button imports Sparkle), but there is no shared context provider, theme object, or runtime configuration layer. Theming is handled entirely through CSS custom properties toggled by a data-theme attribute on an ancestor element, which keeps the runtime footprint at zero for theme switching.

Tech Stack: Built with React 19 (peer dependency, also supports React 18) and TypeScript in strict mode, bundled with Vite using vite-plugin-dts for type declaration generation. The published package is ESM-only (type: module), ships a single dist/performative-ui.js entry plus a separate dist/performative-ui.css. No runtime dependencies beyond React; the docs site (a separate Vite build target) additionally uses react-router-dom for its own navigation, which is not part of the published library.

Code Quality: No test suite exists in the repository (no *.test.*/*.spec.* files), so correctness relies on manual verification against the docs site and TypeScript’s static checking. That said, TypeScript usage is consistently strict across all ~30 components and 4 hooks: every prop interface is exported, generics are used correctly for the polymorphic Button (as prop with ComponentPropsWithoutRef<E>), and hooks like useTypewriter use a ref-mirroring pattern to avoid stale closures in a recursive setTimeout loop without pulling in extra state-management dependencies. Naming is consistent (pui- CSS prefix, use* hook prefix), and comments are used sparingly to explain non-obvious workarounds rather than restate code.

API Design: The public API is a single flat import surface (import { Button, Aurora, useTypewriter } from 'performative-ui'), which keeps the initial learning curve very low; there’s no provider tree or config object to wire up before rendering the first component. The polymorphic as prop on Button and the headless hooks give an escape hatch for consumers who want behavior without markup. The tradeoff is that customization beyond the built-in variant/size props happens through CSS custom property overrides rather than a typed theming API, which is simple but less discoverable than a dedicated theme-object pattern.