@paul-portfolio/react
v0.12.10
Published
React components for the Paul Design System
Readme
@paul-portfolio/react
React components for the Paul Design System. Thin, accessible components styled
by @paul-portfolio/css —
the components render semantic markup with class names, and the CSS package
supplies the looks via design tokens.
Install
npm install @paul-portfolio/react @paul-portfolio/css @paul-portfolio/tokens@paul-portfolio/css and @paul-portfolio/tokens are peer dependencies, along
with react and react-dom (>=18).
Setup
Import the token variables and the component styles once, near the root of your app:
import "@paul-portfolio/tokens/tokens.css";
import "@paul-portfolio/css/components.css";Then use the components:
import { Button } from "@paul-portfolio/react";
export function Example() {
return <Button variant="primary">Save</Button>;
}Components
Button
Variants (primary, secondary, outline, ghost, danger), sizes (xs,
sm, md, lg), loading, and an href form that renders an <a>.
<Button variant="outline" size="sm" onClick={save}>Save</Button>
<Button href="/docs" variant="ghost">Docs</Button>IconButton
A square, icon-only button. Requires aria-label since there's no visible text.
Sizes sm and md.
<IconButton aria-label="Close" onClick={close}>✕</IconButton>Input / Textarea
Labelled fields with error and helper text. Input takes a size
(sm/md); Textarea resizes vertically.
<Input label="Email" type="email" error={emailError} />
<Textarea label="Bio" helper="Max 200 characters" />Switch
An on/off toggle. Controlled via checked + onCheckedChange. Give it an
aria-label.
<Switch checked={on} onCheckedChange={setOn} aria-label="Notifications" />Chip
A compact tag, optionally removable and colorable.
<Chip label="Design" onRemove={() => remove("design")} />Modal
An accessible dialog with focus trap, Escape-to-close, and a backdrop. Controlled
via open + onClose.
<Modal open={open} onClose={close} aria-label="Settings">
<h2>Settings</h2>
</Modal>Tooltip / InfoTip
Tooltip wraps any element and shows text on hover. InfoTip is the common
"small i that explains a label" shortcut, built on Tooltip.
<Tooltip content="Copied to clipboard"><IconButton aria-label="Copy">⧉</IconButton></Tooltip>
<InfoTip content="We never share your email." />Card
A surface with optional Card.Header, Card.Body, and Card.Footer.
<Card>
<Card.Header>Plan</Card.Header>
<Card.Body>Pro — $12/mo</Card.Body>
</Card>Badge / Avatar / Skeleton / Spinner
- Badge — a small status label.
- Avatar — a rounded user image with initials fallback.
- Skeleton — a shimmer placeholder for content that's still loading.
- Spinner — an indeterminate loading spinner (
sm/md/lg), announced as a status region.
<Badge>New</Badge>
<Avatar name="Ada Lovelace" src={url} />
<Skeleton width="12rem" />
<Spinner label="Loading results" />Divider
A thin separator rule, horizontal (default) or vertical.
<Divider />
<Divider orientation="vertical" />VisuallyHidden
Renders content that's available to screen readers but hidden visually.
<VisuallyHidden>Loading</VisuallyHidden>AI / LLM app components
A set of interaction-heavy components for building assistant and chat surfaces. All are keyboard-operable and carry an axe test like the rest of the package.
RichTextEditor
A small rich-text editor on a contentEditable region. The toolbar is
configurable (bold, italic, underline, h2, bulletList, orderedList,
code, link), Ctrl/Cmd+B/I/U work from the keyboard, and it emits HTML on
every edit.
<RichTextEditor
label="Prompt"
toolbar={["bold", "italic", "code"]}
onChange={(html) => setDraft(html)}
/>ChatMessage
A chat bubble aligned and coloured by role (user | assistant | system),
with optional avatar, name, and timestamp. Pass pending while a reply is
streaming to show the typing indicator.
<ChatMessage role="assistant" name="Assistant" timestamp="10:30">
Here's the summary you asked for.
</ChatMessage>
<ChatMessage role="assistant" pending />ChatComposer
An auto-growing prompt field. Enter sends, Shift+Enter inserts a newline, empty
messages don't send, and the control locks while busy.
<ChatComposer label="Message" onSubmit={send} busy={waiting} maxLength={2000} />StreamingText
Reveals text a few characters at a time, the way a streamed model reply arrives,
with a caret and a polite live region. Honours prefers-reduced-motion by
showing the whole string at once.
<StreamingText text={reply} speed={2} interval={30} onDone={scrollToEnd} />TypingDots
The three-dot "assistant is typing" indicator. The animation is decorative and
hidden from assistive tech; the label carries the meaning.
<TypingDots label="Assistant is typing" />CodeBlock
A read-only code panel with a language label and a copy button that reports success to assistive tech. Optional decorative line numbers.
<CodeBlock code={snippet} language="ts" filename="stream.ts" showLineNumbers />CommandPalette
A ⌘K command menu. Type to filter (label + keywords), arrow keys to move, Enter
to run, Escape to close, with optional group headings. Follows the
combobox/listbox pattern with aria-activedescendant.
<CommandPalette
open={open}
onClose={() => setOpen(false)}
commands={[{ id: "new", label: "New chat", onSelect: startChat }]}
/>Combobox
An accessible autocomplete — a filtering text input with a listbox popup and full keyboard support. Handy for model/tool pickers.
<Combobox label="Model" options={models} value={model} onChange={setModel} />Toast
Wrap the app in ToastProvider and raise notifications with useToast(). Toasts
stack in a live region (errors announce assertively) and auto-dismiss unless
duration is 0.
const { toast } = useToast();
toast({ title: "Saved", description: "Your changes are safe.", variant: "success" });TokenUsageMeter
A budget bar for LLM token usage: prompt and completion tokens as two segments of
a track sized against maxTokens, with the used total, percent, and an optional
cost estimate. Shifts to a warning tone near the budget and an over tone past it.
<TokenUsageMeter
label="Context window"
promptTokens={3200}
completionTokens={1400}
maxTokens={8000}
costPerMTok={3}
/>cx
A tiny classname joiner used internally, exported for convenience.
cx("card", isActive && "card--active"); // "card card--active"Motion & effects
Motion primitives and effect components, reimplemented on the design tokens
(no animation library). Each pairs with a @paul-portfolio/css stylesheet,
answers prefers-reduced-motion, and is axe-clean. None add a runtime
dependency — the canvas pieces (ParticleText) use the built-in 2D canvas.
Live demos are in Storybook.
| Component | What it's for |
|-----------|---------------|
| ClickSpark | A ring of rays bursts from the press point; wraps a control without swallowing its click |
| BlurReveal | Content resolves from a blur as it rises in (as, delayMs) |
| StarBorder | A conic gradient sweeps the border, tinted from currentColor |
| ShineSweep | A specular bar sweeps diagonally across a button or badge |
| LiquidGlass | An iOS-style frosted surface with a drifting specular highlight |
| TextLoop | Cycles a list of phrases in place, each sliding up |
| SquishSwitch | A role="switch" whose thumb springs across and compresses on press |
| RubberSegment | A role="radiogroup" whose indicator rubber-bands between segments |
| LatticeLoader | A role="status" grid lighting in a travelling pattern, resolving to a check/cross |
| DriftWall | A 3D wall of image tiles, each column drifting at its own speed |
| HoverImageReveal | A text menu revealing a per-row image in a cursor-trailing window |
| LinkPreview | An inline link that raises a floating thumbnail leaning toward the pointer |
| SmoothScrollSlider | A rail whose cards grow toward the centre and coast after a flick |
| LiquidCarveButton | A button a cursor-following blob carves into |
| SpiralPortraitHero / PerspectivePortraitHero / CorridorPortraitHero | Portrait hero compositions — an outward spiral around the copy, a divided four-wall tunnel, and a corridor with side-wall posters |
| LightBloom | A glow blooming from an edge, breathing and pointer-following (CSS, not WebGL) |
| ParticleText | Text as a cloud of canvas particles that assemble and scatter |
| CircularGallery | Cards on a rotating 3D cylinder you spin with a drag |
| PathGallery | Images gliding along a curved CSS motion path |
| RefineFrame | Content resolving from blurred/desaturated to sharp as its status advances (CSS filters, inline SVG status icons) |
| FolderFloat | A folder whose chips float out above it, fanned and bobbing (CSS, no physics engine) |
| BotanicalText | Text grown from tiny flowers and leaves on the 2D canvas (no WebGL) |
Accessibility
Every component ships with an axe test in the package's suite. Components that have no visible text (IconButton, Switch, Spinner) require or default an accessible name, and interactive components expose the right roles and ARIA state.
Portrait hero image actions
All three portrait heroes slow their animation while an image is hovered or focused. Tunnel and corridor stay fixed under pointer movement. Images remain decorative by default; set href for a link or onClick for a button action, and provide alt as its accessible name.
<SpiralPortraitHero
heading="Meet the people"
images={[
{ src: '/portraits/alex.jpg', href: '/people/alex', alt: 'Meet Alex' },
{ src: '/portraits/sam.jpg', onClick: () => openPortrait('sam'), alt: 'Open Sam’s portrait' },
]}
/>License
MIT © Paul Sumido
