Specimen
A measured argument for fewer animations.
Motion has a cost. The question is whether it earns its keep.
Sample copy.
aiux
Guide Design System
Tokens, primitives, and conventions used across aiux.
Updated 2026-05-276 token scalesLight + dark
Foundations
Six token scales plus a z-index stack. Defined in globals.css, exposed as Tailwind utilities.
Color
Semantic CSS variables. Light/dark resolves at runtime. WCAG AA contrast on every paired token.
Surface
background-primary
background-secondary
surface-primary
surface-elevated
Text & accent
text-primary
text-secondary
text-tertiary
accent-primary
Status
border-success
border-warning
border-error
border-info
Surface treatments
.bg-grain
Every hero
.bg-hero-mesh
Homepage only
Typography
Satoshi, self-hosted. Seven steps. Each token bundles size, weight, leading, and tracking.
TokenSizeWeightLeadingTracking
.type-display56px8001.05-0.03em.type-h140px7001.15-0.025em.type-h232px7001.2-0.02em.type-h324px6001.3-0.015em.type-body16px4001.6-0.005em.type-caption14px5001.50.type-eyebrow12px6001.40.08emSpacing
Five semantic aliases over Tailwind's scale.
tight8pxsnug12pxdefault16pxloose24pxroomy32pxRadii
Named by role, not size.
Search patterns…
.rounded-input
Pattern
Confidence visualization
.rounded-card
Unlock 3 more audits
Enter your email to continue.
.rounded-modal
AI UX pattern
.rounded-pill
Elevation
Six shadows. Light and dark variants.
.shadow-flatDisabled, dense lists
.shadow-cardCard resting
.shadow-card-hoverCard hover
.shadow-elevatedCallouts
.shadow-modalDialogs
.shadow-popoverTooltips, menus
Z-index
Seven layers. No raw z-50 in new code.
.z-base0Default flow.z-dropdown10Menus, comboboxes.z-sticky20Sticky headers and CTAs.z-overlay30Backdrop dimmers.z-modal40Dialog content.z-toast50Transient notifications.z-tooltip60Hover tooltips (always topmost)Motion
Four durations, three easings. Default: ease-out-expo.
snap100msToggles, taps
quick180msHover, focus
base280msModals, accordions
deliberate450msPage transitions
Cards
Most reused composition. Shared chrome: rounded-card, border, bg-surface-primary, padding from the spacing scale.
Pattern
Confidence visualization
Show users how certain the model is about each output, not just the output itself. Pair a probability with a plain-language qualifier so non-technical readers can act on it.
Trustworthy & reliable AI4 min
Variants
Prompt
Handoff to Claude Code
Inline action — copy / submit
Adaptive interfaces
12Surfaces that reshape themselves based on user signal.
Dense — list cell
Logo strip
Self-hosted SVGs. Navy filter. CSS-only marquee at 100s for peripheral motion.
Data
company-logos.tsComponent
CompanyLogoCarouselSizesxs · sm · md · lg
News strip
Timeline of newsletter issues on /news. Today's row gets a tinted surface and a status pill.
May 28
AI UX Daily: Users reject AI-first search — DuckDuckGo installs spike 30%Today
Three stories about how designers need to rethink interfaces when AI agents have real autonomy, from trading stocks to scheduling.
9 min readMay 27
AI UX Daily: Context Wins, Honesty Matters, Design Systems Evolve
As AI agents handle longer tasks, design systems need memory, prototypes need authenticity, and designers need a new vocabulary.
9 min readMay 26
AI UX Daily: Google's Real-Time AI Design, Notion's Workspace Agents
Google launches a real-time AI design tool, Notion opens its workspace to native agents, and Replit ships parallel coding.
8 min readEmail capture
Email + submit pair, used across the audit unlock, newsletter signups, pattern pages, and guides. Same primitives, three densities.
Inline · default
Stacked · audit unlock
Unlock 3 more audits
Drop your email. We'll send the report and unlock 3 more runs.
Compact · footer / sidebar
Shared component: InlineNewsletterSignup. Variant hero / inline / stacked, plus darkBackground and secondary flags.
Primitives
Button, Dialog, and Input live in src/components/ui/. Supporting hooks: useScrollLock, useClickOutside, useFocusTrap.
Button
Dialog
Backdrop click, Escape, and the Cancel button all close. Focus is trapped inside and returned to the trigger.
Input
With a description below.
Email must include an @
size='sm' for dense surfaces
Accessibility
- 01
WCAG 2.2 AA contrast on every paired token.
- 02
Keyboard navigation on every interactive surface. No bare focus removal.
- 03
Focus rings via --ring-focus. Dark-mode aware.
- 04
next/font handles swap with adjustFontFallback. No layout reflow.
- 05
Required alt text on images. Empty alt only for decorative.
Conventions
Each tied to a specific production incident.
Self-host every visual asset
No CDN dependencies. Fonts and logos served from our domain.
Hotjar recording · Feb 2026
Explicit width/height on media
Hardcoded dimensions on every img, SVG, and video. Survives a missing stylesheet.
CLS spike · Apr 2026
adjustFontFallback: "Arial"
Size-adjusted fallback matches Satoshi's metrics. No reflow on font swap.
Font CLS fix · Apr 2026
Three layers on cached pages
Re-throw on DB error, runtime guard against empty renders, live-page watchdog.
/news ISR cache · May 2026
Open work
Run npm run design-audit:report for the live counts.
01
1,169 raw Tailwind color uses
Mostly in pattern demo components and SkeletonLoader. New uses are blocked at commit.
02
62 raw z-index values
z-10 through z-50 scattered across modals and sticky bars. Migrating to z-modal / z-sticky / z-overlay.
03
69 arbitrary font sizes
text-[14px], text-[18px], etc. Should use the type-* utilities.
04
108 light-only colors without dark variants
bg-white / text-black without dark: counterparts.
05
Migrate 5 modals to the Dialog primitive
Primitive is shipped — PaywallModal, WelcomeModal, EmailReportModal, DownloadPDFModal, SearchModal still inline their own backdrop and focus logic.
06
Migrate 4 search inputs to the Input primitive
Primitive is shipped — SearchBar, UnifiedSearchBar, AdvancedSearchBar, SmartSearchChat still diverge on keyboard behavior.
07
9 card variants → Card
Shared chrome, isolated implementations.
08
No Storybook
This page is the reference instead.
09
No automated a11y in CI
axe-core in Playwright pending.