Buttcoiners/ UI
    Public reference · v1

    UI building blocks for directories that need to last.

    A practical system extracted from a production directory: semantic foundations, accessible primitives, composable browsing patterns, and optional business modules that stay optional.

    01Foundations02Primitives03Components04Directory patterns05Optional modules

    Foundations

    The foundations layer.

    Semantic color

    Core

    Role-based tokens keep surfaces, text, borders, and actions consistent across themes.

    src/styles.css
    Background
    Primary
    Secondary
    Muted
    Dark surface
    Dark action
    Dark layer
    Dark muted
    Use when
    Styling any interface color.
    Accessibility
    Pair foreground and background roles; do not reduce muted text opacity.
    Performance
    CSS variables change theme without rerendering the component tree.
    className="bg-background text-foreground border-border"

    Type & rhythm

    Core

    A compact type scale groups related metadata tightly and separates changes in purpose with deliberate spacing.

    src/styles.css

    Archive no. 24

    Modernist field guide · 1964

    The record

    An illustrated field guide from the collection, preserved with its original attribution.

    Recorded in 1964 · Catalogued today

    Use when
    Structuring headings, body copy, labels, and dense metadata.
    Accessibility
    Preserve heading order and keep body text at 14px or larger.
    Performance
    System-first fallbacks prevent invisible text during font loading.

    Motion contract

    Core

    Fast feedback uses 200ms; layout transitions use 300ms; ambient motion is removable.

    src/design-system/tokens.ts
    Ready
    Use when
    Adding state feedback or explaining a spatial change.
    Accessibility
    Honor reduced-motion preferences for ambient motion and never rely on motion alone.
    Performance
    Animate opacity and transforms; avoid layout-triggering properties.

    Primitives

    The primitives layer.

    Button

    Core

    The single command primitive for primary, secondary, quiet, and destructive actions. Foreground quiet commands lead; compact evidence links and muted utilities support.

    src/components/ui/button.tsx
    Collection archive · Record 24

    Use when
    A user action changes state, submits data, or opens another interface.
    Accessibility
    Icon-only buttons require an accessible name; disabled state must be programmatic.
    Performance
    No runtime styling dependency beyond class composition.
    <Button variant="outline">Refine</Button>

    Input

    Core

    Text entry with stable height, semantic tokens, and visible keyboard focus.

    src/components/ui/input.tsx
    Use when
    Collecting short free-form values such as search terms.
    Accessibility
    Always associate a visible or screen-reader label; placeholder text is not a label.
    Performance
    Debounce network-backed search, not the input value itself.
    <Input aria-label="Search directory" placeholder="Search records…" />

    Select

    Core

    A keyboard-accessible option menu built on Radix UI.

    src/components/ui/select.tsx
    Use when
    Choosing one value from a compact, known set.
    Accessibility
    Provide an accessible name and keep option labels concise and unique.
    Performance
    Use searchable patterns instead for long option sets.
    Relationships
    External: Radix Select.

    Range slider

    Core

    A touch-friendly single or dual-thumb range control with optional live labels.

    src/components/ui/slider.tsx
    Range24–72
    Use when
    Filtering bounded numeric data where approximate selection is useful.
    Accessibility
    Name every thumb and provide a textual summary of the selection.
    Performance
    Update locally while dragging; defer expensive queries until interaction ends.
    Relationships
    External: Radix Slider.

    Components

    The components layer.

    Active indicator

    Core

    A compact visual signal that a filter or control contains an active value.

    src/components/ds/ActiveIndicator.tsx
    Use when
    Space is constrained and the parent control already has an accessible label.
    Accessibility
    Decorative only; the parent must expose state through text or aria attributes.
    Performance
    Uses transform and opacity only.
    Relationships
    Composes: Semantic color, Motion contract.

    Optimized image

    Core

    A stable image frame with explicit priority, loading, decoding, and placeholder behavior.

    src/components/ds/OptimizedImage.tsx
    Abstract placeholder landscape

    Reserved 3:2 frame · lazy · async decoding

    Use when
    Rendering any directory image or detail media.
    Accessibility
    Alt text describes the image purpose; decorative images use empty alt text.
    Performance
    Reserve aspect ratio, prioritize only above-fold media, and lazy-load the rest.

    Floating panel

    Reusable pattern

    A portal-based mobile surface for focused controls without covering the whole directory.

    src/components/ds/FloatingPanel.tsx
    Use when
    A compact mobile trigger needs a larger temporary control surface.
    Accessibility
    Provide a name and manage focus in the consuming flow when modal behavior is required.
    Performance
    Mounts only while open; portal placement avoids clipping ancestors.
    Relationships
    Composes: Button, Motion contract.

    Blog receipt

    Project-specific

    Inline evidence card in articles: poster, exact quote, critic, date and Bitcoin price then, placed with a {{receipt:<quote-id>}} line.

    src/components/blog/BlogStory.tsx
    Use when
    Showing a cited quote visually inside long-form storytelling.
    Accessibility
    Labelled aside; poster alt repeats the quote and critic.
    Performance
    Server-rendered from the article loader data; lazy, display-sized poster images.
    <BlogReceipt q={quote} index={1} />

    Blog TL;DR

    Project-specific

    Answer-first key-facts box at the top of articles, computed from the archive.

    src/components/blog/BlogStory.tsx
    Use when
    Giving readers and AI answers the numbers before the story.
    Accessibility
    Labelled aside with a real heading and list.
    Performance
    Static markup in server HTML.
    <BlogTldr facts={article.keyFacts} />

    Critic dossier

    Project-specific

    Critic page sections: stat chips, short version, published story, timeline of takes with full quote text and poster, price then vs now table, room mockups and visible FAQ.

    src/components/author/AuthorDossier.tsx

    March 2013 · BTC $47

    “It will never be a currency.”

    Read the full record →

    Use when
    Turning a critic page into a readable, citable record instead of a poster grid.
    Accessibility
    Each section has a real heading; quotes are blockquotes with dated time elements.
    Performance
    All text in server HTML from loader data; posters lazy at thumbnail size; rooms mount near the viewport.
    <AuthorTimeline quotes={quotes} name={author.name} onOpen={openQuote} />

    Series chips

    Project-specific

    Pill toggles that filter the blog index by series.

    src/components/blog/RelatedArticles.tsx
    Use when
    Filtering a short list by one category at a time.
    Accessibility
    Group has a label; each chip exposes aria-pressed.
    Performance
    Filters in memory; all articles stay in server HTML for crawlers.
    <SeriesChips options={opts} value={id} onChange={setId} />

    Directory patterns

    The directory patterns layer.

    Directory toolbar

    Reusable pattern

    Search, facets, range filters, sorting, and view controls composed around one result set.

    src/components/FilterBar.tsx

    3 of 3 records

    Modernist field guide

    Books · 192 pages

    Coastal observatory

    Places · Open daily

    Archive no. 24

    Collections · 38 objects

    Use when
    Users need to narrow or reorganize a collection without leaving the page.
    Accessibility
    Every control is named; active state and result count update in text.
    Performance
    Apply cheap local filters immediately and debounce only remote requests.
    Relationships
    Composes: Input, Select, Active indicator, Floating panel.

    Responsive results

    Reusable pattern

    The same records can appear as cards, a list, or a table without changing their identity.

    src/components/QuotesDirectory.tsx

    Modernist field guide

    Books · 192 pages

    Coastal observatory

    Places · Open daily

    Archive no. 24

    Collections · 38 objects

    Use when
    A directory serves both visual browsing and comparison-heavy workflows.
    Accessibility
    View controls expose pressed state; DOM order remains logical in every layout.
    Performance
    Keep item keys stable and avoid loading off-screen media eagerly.
    Relationships
    Composes: Optimized image, Button.

    Directory states

    Reusable pattern

    Loading, empty, no-results, and progressive-loading states preserve layout and next actions.

    src/components/QuotesDirectory.tsx

    No records yet

    Create the first record to begin.

    No matches

    Use when
    A collection is fetched, filtered, or incrementally revealed.
    Accessibility
    Status changes use understandable text and do not trap focus.
    Performance
    Skeletons reserve final geometry; sentinels avoid scroll listeners.

    Deterministic inserts

    Reusable pattern

    Promotional or editorial content is inserted by row rules without corrupting record order.

    src/lib/interleaveWidgets.ts
    Record 01
    Record 02
    Sponsored · clearly labeled
    Record 03
    Use when
    A directory needs non-record content between predictable result groups.
    Accessibility
    Inserted content identifies its purpose and does not interrupt keyboard order.
    Performance
    Compute placement once from stable inputs rather than measuring the DOM.

    Optional modules

    Add only when the product earns it.

    Commerce actions

    Optional

    Variant selection, cart state, and hosted checkout can be attached to eligible records.

    src/components/AddToCartButton.tsx

    Variant

    Choose an eligible option

    Cart

    Persist selected records

    Use when
    Directory records represent purchasable products.
    Accessibility
    State availability and price are textual; selection precedes the purchase action.
    Performance
    Load commerce clients only for projects that enable the module.
    Relationships
    External: Shopify Storefront API, Cart store.

    Collector sheet

    Reusable pattern

    An intent-led purchase surface keeps product configuration out of the factual reading flow.

    src/components/PosterCollectorSheet.tsx

    Collect this poster

    Choose an edition after deciding to collect.

    Use when
    A documented object becomes purchasable only after the visitor signals collecting intent.
    Accessibility
    The modal traps focus, names every edition and price, and returns focus to its trigger.
    Performance
    Mount commerce choices on intent while reusing the existing cart client.
    Relationships
    Composes: Button, Commerce actions. External: Radix Dialog.

    Poster lifestyle scene

    Reusable pattern

    Five single-poster and three collection presets project intact artwork into measured physical frame openings across mobile and desktop.

    src/components/PosterRoomScene.tsx

    Held statement

    Sofa close-up

    Sunlit cabinet

    Bright bathroom

    Light editorial

    Statement pair

    Salon wall · six prints

    Light collection · eight prints

    Use when
    A visual object benefits from contextualizing scale and atmosphere before commerce begins.
    Accessibility
    Room alternatives expose names, selected state, keyboard controls, and distinct environment descriptions.
    Performance
    Only the selected and previous complete room mount near the viewport. Parallel decoded images reveal atomically; a bounded cache reuses requests. One source canvas and aperture masks keep artwork inside its frame.
    Relationships
    Composes: Optimized image, Button, Collector sheet.

    Promotional inserts

    Optional

    Clearly labeled sponsor or editorial placements can join the feed without becoming records.

    src/components/InFeedCard.tsx

    Promotion

    Clearly labeled

    Frequency

    Predictably capped

    Use when
    The business model requires promotion inside the browsing flow.
    Accessibility
    Mark promotions clearly and exclude them from primary result counts.
    Performance
    Cap frequency and lazy-load nonessential media.
    Relationships
    Composes: Deterministic inserts.

    Theater browsing

    Optional

    An immersive detail view supports keyboard, buttons, and touch navigation between records.

    src/components/QuoteLightbox.tsx

    Immersive record preview

    Use when
    Large imagery is the primary browsing experience.
    Accessibility
    Provide visible navigation, focus management, Escape handling, and dialog semantics.
    Performance
    Lazy-load the viewer and adjacent media only.
    Relationships
    Composes: Optimized image.

    First-visit nudge

    Project-specific

    A removable discovery cue draws attention to an unfamiliar high-value filter once.

    src/features/filter-nudge/index.ts
    Use when
    Research shows an important control is consistently overlooked.
    Accessibility
    Stop after interaction, respect reduced motion, and never block the control.
    Performance
    Session-gated and transform-only; remove cleanly through one feature flag.
    Relationships
    Composes: Directory toolbar.