Components

The live style guide is the authoritative component reference. Every component ships with a runnable showcase route under /components/* that demonstrates props, variants, and rendered output side-by-side with the Vue source.

Run the style guide:

npm run dev
# → http://localhost:3030/components

What ships today

Pagination + result-display family (added 2026-05-21):

Research-publishing family (added 2026-05-22):

TTI identity family (added 2026-05-22):

Geospatial family (added 2026-05-22):

Forms wrapper family (added 2026-05-22):

Native chart family (Priority B — closed 2026-05-22):

Reports section

Finished-narrative deliverables — paper, PDF, print, or web-hosted long-form. The reader reads top-to-bottom; they don't pivot or filter. Components live in app/components/ like everything else, but demos live under /reports/<kebab> (with a landing at /reports).

Visualizations section

Interactive data surfaces — BI dashboards, R artifacts, native charts. The reader pivots, filters, drills in. Same pattern as Reports (flat components, grouped routes), but a different section because the chrome and posture are different (provider chip, sandbox, source caption).

See ADR-0008 for the positioning rationale (why data-display stays flat in /components/, why Reports and Visualizations get their own sections, and the criteria for adding a future route group).

The showcase pages expose Vue (template source), HTML (rendered DOM), and — where applicable — Source (the component SFC) tabs via the TuxExample primitive.

Platform-aware chrome family (added 2026-05-22):

These ship together under the platform-aware banner. They cover the brand-vs-chrome split documented in platform-awareness.md: one component tree, platform-adaptive at the chrome layer. The tux-scrollbar.css utility ships alongside (auto-imports via globals.css) and branches scrollbar styling per host via the data-platform attribute set by useTuxPlatform().

Pattern coverage — "want X? use Y"

If you're about to build something, check this map first. The catalog covers more than the file names suggest, and shipping a duplicate component because the existing one had a non-obvious name is the single most common failure mode.

If your need isn't here, scan /components (or app/utils/tuxCatalog.ts, the census the catalog test enforces) — there are ~140 Tux* components and this map only highlights the ones with the easiest-to-miss names.

Conventions

Prop & emit vocabulary — the words and what they mean

Ratified 2026-08-19 after a full-catalog vocabulary audit. TuxBadge and TuxSkeleton are the reference implementations. New components MUST use these words with these meanings; deviations listed below are grandfathered until the next major.

Two meanings of tone, on purpose: product surfaces use the semantic family (status colors); marketing/editorial surfaces (TuxCTA, TuxCardSlab, TuxPhotoGrid, …) use brand-paint values. Both are "which color is this thing" — that's the invariant. Brand-paint values name the actual paint (maroon, gold, charcoal, navy, neutral) — never alias one paint word for a different color.

The v2.0.0 rename batch LANDED 2026-08-19 (see CHANGELOG "Breaking"): TuxFactoid.columns, TuxBetaRibbon.kind, TuxTabs.variant, TuxChartGauge band tone: success·warning·error, TuxCodeMaroon.tone (error replaces alert), TuxTestimonial.tone, TuxConfirmDialog drops the danger alias, select replaces pick (TuxConversationList/TuxSuggestionChips) and citation open (TuxCitations/TuxInlineCitation), stacked replaces stack (TuxStatComparison/TuxMapLegend), TuxFigureCaption/TuxTableCaption label replaces free-form kind, TuxRichTextEditor's duplicate bare update emit removed, and TuxTreemap joins the family hover emit.

Deviations kept, by decision: TuxResultCount emits update:page (a legitimate v-model:page) while TuxPagination uses update:modelValue — both are idiomatic Vue; TuxCommentThread's comment:*/thread:* colon namespace; TuxCommandPalette.open meaning "panel opened".

Composition standards for cases where a slot or prop combination shows up across multiple Tux* components or consuming apps. Capturing them here keeps consumers from inventing different icons or labels for the same affordance.

Chat-message actions

TuxChatMessage exposes a #tools slot for the row of small actions that sit below an assistant response (copy, regenerate, like, etc.). The Vercel AI Elements Actions reference shows the pattern; TUX standardizes on this five-icon set so consumers don't pick five different copy icons:

Order convention: Copy · Regenerate · Share · Helpful · Off when all five appear. Use a subset if the surface doesn't support an action (e.g., no regenerate when the response is already final). tti-ai-studio-session.vue is the canonical example using a Copy / Helpful / Off subset.

Style: icon + label (label can hide at narrow widths), font-size text-xs, color text-text-muted, hover transitions to text-brand-primary. Sits in a flex row below a border-t rule.

Form validation — when to use which

Backstage's design system dedicates 38 frames to form validation (inline errors, dialogs, banners) because where validation lives matters as much as what it says. TUX standardizes on four placements; the right one depends on scope (field / form / page / session) and severity (advisory / blocking).

Decision tree:

1. Single field is wrong → inline field error
2. Multiple fields wrong + user tried to submit → inline form summary + keep inline errors
3. Destructive action being submitted → blocking dialog
4. Session-level constraint (ITAR, auth, rate limit) → page/session banner
5. Form succeeded → toast

Anti-patterns to avoid:

• Modal dialog for a single bad field — friction without value; the inline error is faster
• Banner for a single bad field — wrong scope; the user has to find which field
• Inline error for a session-level issue — the user fixes the field but can't progress; root cause lives above
• Toast for an error — transient and easily missed; use banner or dialog for anything the user needs to act on

Canonical references for each pattern in real composition: forms/inline-validation.vue (field-level), forms/all-in-one.vue (form summary), landscape-dashboard ITAR alert (session banner).

First-run AI surfaces — Examples / Capabilities / Limitations

When a consumer surface needs richer first-run framing than the single- block TuxEmptyState kind="first-run" (e.g. tti-ai-studio's new-session splash), use ChatGPT's canonical three-column taxonomy. Each column sets a different expectation before the user types their first prompt:

Compose with <TuxFactoid density="3"> (numerical-statistic style) or a 3-up <TuxCard> grid (richer per-cell layout). The taxonomy is the discipline; the components rendering it are the consumer's choice. No dedicated TuxFirstRunTaxonomy component is needed — the value is the framing, not the chrome.

Anti-patterns to avoid:

• Single-paragraph welcome. "Welcome to tti-ai-studio." reads as marketing, not orientation. The three columns set expectations before the user invests their first prompt.
• Marketing tone in research IT. ChatGPT's first-run is a consumer surface ("Hi, what's on your mind today?"). Research-IT first-run should be quieter and more functional — "Recent session was about X · Pick up where you left off." Keep the taxonomy; drop the marketing voice.
• More than three columns. The discipline is exactly three — the gain over a flat "welcome" is the parallelism. Four blurs it.

Reference frame: reference/figma-cache/chatgpt-ui-kit-ai-chat/screens/new-chat.png. Absorbed 2026-05-21 from the ChatGPT UI Kit Figma file.

MCP tool output — inline card / inline carousel / full screen

When an MCP (Model Context Protocol) tool inside tti-ai-studio returns output to render in the chat, three display tiers cover the spectrum. Each is the canonical TUX composition; pick by the density and interactivity of the result.

Decision tree:

1. One static result + read-only → inline card (TuxArtifact).
2. One interactive app surface → inline card (TuxMcpEmbed).
3. Multiple comparable results + scanning → inline carousel.
4. Heavy data / app needs >½ chat width → full screen.

Each tier has a skeleton state for the loading window — TuxMcpEmbed ships its own (three shimmer bars + a content block, honors prefers-reduced-motion); Nuxt UI 4's UChatShimmer covers TuxArtifact inline; TuxSkeleton covers full-screen loads.

Anti-patterns to avoid:

• Full-screen for a one-line answer. The takeover surface is expensive; if the response fits a sentence, just render it in the chat body.
• Inline carousel for two items. Use two side-by-side <TuxArtifact> blocks (or a single card with a comparison callout) — the carousel chrome (arrows, dots, advance buttons) overweights two items.
• Inline card when the result is a list. A 12-result tool dump inside one card is unreadable; promote to inline carousel.

Reference frame: reference/figma-cache/mcp-apps-for-claude/frames/. Absorbed 2026-05-21 from Anthropic's official MCP Apps UI kit v1.1.

Faceted vs relational filtering — when to use which

Two filter components, two shapes of question. Reach for the one that matches what the user is actually doing — they're sisters, not substitutes.

Anti-patterns:

• TuxFilterPanel for relational predicates. If you find yourself generating a facet bucket per >50% / >60% / >70% threshold, the user wanted a numeric comparator. Switch to TuxRuleBuilder.
• TuxRuleBuilder for "owner = X." If the dominant axis is multi-select narrowing across a known set, the rule builder makes the user click 3× for what a single facet checkbox covers. Use facets and keep the rule builder for the predicates that don't fit.
• Nesting beyond 3 levels. TuxRuleBuilder caps depth at 3 by default. Deeper trees signal the query should be split into named saved views the user composes, not a single deeply-nested predicate.

Empty states — no decorative illustrations

TuxEmptyState deliberately avoids the saturated-cartoon illustrations common in consumer-SaaS empty-state kits. TUX is research-publishing; editorial restraint outweighs the "consumer SaaS expectation" of a friendly mascot. Empty states use a Lucide icon + heading + body + optional CTA. If warmth is needed, place a real photograph (a future TuxPhotoCard — roadmap; today a TuxCaptionedMedia) next to — not inside — the empty state.

This stance was reaffirmed against the Empty State Illustration Kit absorption (2026-05-21). The five kind presets (no-data / no-results / not-found / no-permissions / first-run) cover the real scenario taxonomy; 200 generic illustrations would not.

Focus rings — the universal rule owns them

The layer ships ONE focus affordance: *:focus-visible in globals.css applies the themed two-ring --shadow-focus (--focus-ring-inner / --focus-ring-outer, remapped per theme — black-on-white in high-contrast). Components must NOT restate their own ring: a per-component outline: 2px solid <color> double-draws on top of the shadow, and a per-component outline: none silently suppresses the universal ring (2026-08-12 audit found four competing recipes across ten components — all removed).

Exactly two sanctioned exceptions:

1. SVG child elements (<rect>, <path>, …) — box-shadow cannot render on them, so a focusable SVG child carries its own outline: 2px solid var(--focus-ring-outer) (the themed token, never a brand color). TuxTreemap's cells are the canonical case. Plot-level capture rects may instead use the documented wash-fill alternative (TuxChartLine's hover capture).
2. @media (forced-colors: active) blocks — Windows High Contrast rings use system colors by design; leave them.

Motion primitives — six canonical transitions

Absorbed from the Tailwind Headless UI w/ Animations Figma kit and reaffirmed by the chart-family entrance animations shipped 2026-05-22. Every Tux component that animates uses one of these six patterns. Designers and contributors should reach for the existing primitive, not invent new motion.

Plus three component-level entrance primitives shipped 2026-05-22 in tux-component-motion.css:

• Mount fade-up (4px slide + fade, 220ms) — opt-in via .tux-mount-in on a section; immediate children animate in with optional stagger via --tux-mount-stagger-index.
• Mount fade (no slide, 180ms) — for chrome surfaces like alerts and badges that shouldn't move.
• Mount scale (96% → 100%, 200ms) — for popovers / floating chrome that originate from a trigger.

Plus six chart-family entrance primitives in tux-chart-motion.css:

• Lines draw on via animated stroke-dashoffset.
• Bars scale-Y from baseline (or scale-X horizontally).
• Areas + top-lines rise from scale-Y 0.94.
• Donut slices spin in -12° → 0, staggered.
• Scatter dots pop from scale(0), staggered.
• Gauge fill sweeps via stroke-dashoffset; needle swings.

All motion primitives collapse to instant on @media (prefers-reduced-motion: reduce). This is non-negotiable — no contributor escapes it, no "delight" affordance ignores it.

Chart tooltips — consistent pattern across the family

Every interactive chart in the native chart family uses the same tooltip pattern, shipped 2026-05-22 (TuxChartLine, TuxChartBar, TuxChartArea, TuxChartScatter) and extended to TuxChartDonut, TuxChartSunburst, and TuxTreemap 2026-08-12:

1. Hover via pointer or focus via keyboard — one tab stop per chart. Lines / Areas / Bars accept a focusable rect across the plot area; Scatter / Donut / Sunburst make the <svg> itself the single focusable surface. Arrow keys cycle the active item as a roving cursor (scatter points in x order; donut slices clockwise; sunburst segments in hierarchical order — group, then its children). Never make every data point a tab stop: a 500-point scatter must not inject 500 tab stops. Heatmap keeps the single tab stop but its roving cursor is two-dimensional — Left/Right walk columns, Up/Down walk rows — because collapsing a matrix to a 1-D walk would alias the axes. Treemap is the one exception — its cells are real drill-in buttons (role="button", Enter/Space drills, Backspace drills up, arrows walk cells), so per-cell focus is the correct semantic.
2. Visual highlight — vertical guide line + per-series focus dots (Line / Area); column-wash on the active category (Bar); active-dot grow +2px (Scatter).
3. Branded tooltip card with the active label, per-series values, and (where applicable) totals, comparison overlays, or previous-period readouts.
4. Auto-flip — when the active point sits past 60% of chart width, the tooltip flips to the left of the cursor so it doesn't overflow the parent container on the right.
5. hover emit — every chart emits hover with the active payload so consumers can sync hover state across multiple panels (e.g., highlight the matching row in an adjacent table).
6. tooltip prop — pass :tooltip="false" to disable when the chart is used in a print / PDF / non-interactive context.
7. Native SVG <title> fallback remains on all hover-capable elements for AT users who don't see the branded card.

When building a new chart that needs hover behavior, follow this pattern rather than inventing a parallel one. The visual + a11y + emit contract is the canonical TUX chart-tooltip shape.

Ideas not yet shipped

The catalog originally listed several components here. As of the current cycle, every aspirational entry has shipped. New components land when a consuming app (Landscape, tti-ai-studio, marcom WordPress kit) needs them; open an issue or ping the maintainer to add a row.

Guidance for adding a new component

1. Write it against Nuxt UI where possible — inherit a11y, theming, color-mode integration for free. Only go native when a Nuxt UI primitive fights TTI branding too hard to override cleanly (see TuxCard for an example of when that happens).
2. Use container queries, not viewport media queries, for any layout that shifts based on width. Tux components get embedded at varying widths — full-page, sidebar tile, narrow article column, demo wrapper, modal body. Viewport queries firing on a 1200px viewport while the component lives in a 600px column is the single most common bug we hit.
   The pattern:

   .tux-component {
     container-type: inline-size;
     container-name: tux-component;
     /* base styles, mobile-first */
   }
   
   @container tux-component (min-width: 44rem) {
     .tux-component__layout {
       grid-template-columns: 1.4fr 1fr;
     }
   }
   

   
   Use cqi units in clamp() for fluid typography that scales with the container, e.g. font-size: clamp(2rem, 1.2rem + 4.5cqi, 3.5rem).
   Viewport queries are still right when the component does something inherently page-layout-relative — breaking out of an article column with negative margins, or floating into the page gutter. TuxCaptionedMedia's align="wide" and align="right" are the canonical examples; both keep @media queries with an explanatory comment.
3. Hover/floating UI inside a bounded canvas (tooltips, popovers, dropdowns) should flip placement near canvas edges — anchor with right/bottom past the midpoint instead of left/top. See TuxTreemap's tooltip handler for the canonical pattern.
4. Add a showcase route at /components/<kebab-name>. Use TuxExample with at least a vue prop so the Vue template is exposed. If the component is load-bearing for the brand, also pass source so readers can see the SFC.
5. Dogfood TuxPageHeader at the top of the page — keeps visual rhythm consistent across every component demo.
6. Add the entry to app/app.vue nav, app/pages/index.vue Foundations/Components grid, and app/pages/components/index.vue table.
7. Update CHANGELOG.md under Unreleased → Added.
8. Run the local guards before you push — don't wait for CI to find what you could catch in seconds while the component is still fresh in your head:
   • npm run lint + npm run typecheck — style + types.
   • npm test — catalog conformance plus the mounted component suites (tests/components/*.nuxt.test.ts, nuxt environment via // @vitest-environment nuxt docblock, mounted with mountSuspended). New interactive behavior — keyboard contracts, persistence, emits — should land with a mounted test; the chart tooltip suites are the house exemplars.
   • npm run audit:tokens — every var(--token) you wrote resolves to a defined token (or fallback / known external namespace). Catches the --surface-base class of bug (undefined token → renders transparent), invisible to typecheck and the contrast audit.
   • npm run generate && npm run audit:a11y — structural axe-core pass (roles, landmarks, accessible names, nesting) over your new showcase page. npm run audit:contrast covers color separately. All three are blocking in CI, so a clean local run is a clean PR.

A component that skips any of these is invisible to future readers — the style guide is its own documentation, so being in the guide is the definition of "shipped."