Plumb Design System
Every token, component, and pattern used in buoy-site - documented, live, and continuously checked for drift.
Tokens
Colors, typography, spacing, and effects. The raw values every component is built from.
Color Tokens
All colors are CSS custom properties under @theme in src/styles/global.css. They respond to light mode automatically.
Navy
Brand - Buoy Orange
Accent - Lavender
Sunrise
Text
Semantic
Typography
Three font families, each with a specific role. Set via CSS variables in global.css.
Type Scale
npx ahoybuoy drift check Spacing
Section spacing tokens. Element-level spacing uses Tailwind's default scale.
Effects
Glow utilities, text gradients, and animation classes defined in global.css.
Glows
Text Gradients
Motion
The nautical physics model. Every transition, animation, and interaction follows these principles.
Motion
All animation in Plumb follows a nautical physics model. The โต boat is the system mascot - its motion vocabulary defines how every transition feels.
Keyframe Reference
Motion Choreography - The Boat Escape
Five automated phases play out when the page loads. Phase 6 is user-triggered - an interactive physics system active at any time. Each uses a different easing curve or physical model.
rotate(vx ร 1.5deg) capped ยฑ20ยฐ. Boat wraps horizontally - exits one edge, re-enters from the other. Release underwater โ bobberPop spring (Phase 5). Landing โ splash + resumeDrift ease-in (Phase 4) then drift seek.Easing Tokens
Components
Live instances of every component, every variant. No mocks - what you see is what ships.
FeatureCard
src/components/FeatureCard.astro With Link
Cards with href get a hover glow, clickable title, and a Learn more CTA at the bottom.
Without Link
Static cards omit the link affordance entirely. Same token usage throughout.
Minimal
No icon, no examples, no link. Just a title and description using the same border and bg tokens.
Terminal
src/components/Terminal.astro DocTerminal
src/components/DocTerminal.astro Static terminal for docs. Unlike Terminal.astro, renders all lines immediately - no animation delays. Has a copy button in the title bar.
CodeBlock
src/components/CodeBlock.astro <div class="">npx ahoybuoy drift check</div><div class="">npx ahoybuoy show tokens</div> <div class="">export default {</div><div class=""> extends: 'buoy:recommended',</div><div class=""> rules: {</div><div class=""> 'no-hardcoded-colors': 'error',</div><div class=""> 'no-arbitrary-spacing': 'warn',</div><div class=""> },</div><div class="">}</div> <div class=""><span class="text-slate-dark select-none mr-4 w-6 inline-block text-right">1</span>import { tokens } from './tokens'</div><div class=""><span class="text-slate-dark select-none mr-4 w-6 inline-block text-right">2</span></div><div class="bg-buoy/10 -mx-4 px-4"><span class="text-slate-dark select-none mr-4 w-6 inline-block text-right">3</span>const color = '#ff0000' // โ drift!</div><div class=""><span class="text-slate-dark select-none mr-4 w-6 inline-block text-right">4</span>const bg = tokens.navy // โ token</div> Flags
src/components/Flags.astro CLI flag reference list for docs pages. Renders a scannable list of flag names, descriptions, required badges, and defaults.
--config Path to buoy config file (default: buoy.config.mjs) --format Output format: pretty | json | table (default: pretty) --fix Auto-apply suggested token fixes --token API token for cloud features required WaveBackground
src/components/WaveBackground.astro Animated hero background. Always position: absolute; inset: 0 - wrap in a relative overflow-hidden container with a defined height.
Patterns
Recurring compositions built from the token primitives above.
Section Header
Section Title
Supporting description in text-slate. Always below the heading, never above.
Inline Code
Run npx ahoybuoy drift check in your repo root. It reads buoy.config.mjs automatically.
CTA Row
Checkmark Benefit List
Primary benefit title
Supporting description. One or two lines, parallel structure across all items.
Secondary benefit
Keep descriptions parallel in structure and length to the item above.
FAQ Accordion
Is the free tier really free forever?
How does the GitHub App work?
PDF / Conversion Badges
Limited Availability Notice
* Limited availability
Only 100 founding member spots. Once they're gone, standard pricing applies.
Pricing Tier Card
Status Badges
Conversion
Lead capture components. Each wraps LeadMagnetForm in a different layout context.
LeadMagnetForm
src/components/LeadMagnetForm.astro Email capture form primitive. Used inside all lead magnet variants. Handles submit, loading, success, and error states.
LeadMagnetCallout
src/components/LeadMagnetCallout.astro Inline callout card for embedding lead capture in article or docs context. Switches to horizontal layout on large screens.
20 warning signs of design system drift
A checklist for your next code review. Spot drift before it compounds.
No spam. Unsubscribe anytime.
LeadMagnetCTA
src/components/LeadMagnetCTA.astro Full-width centered section CTA. Used at the bottom of content pages to offer a related PDF download.
Where does your design system stand?
Assess your maturity level and get a roadmap for what to fix next.
No spam. Unsubscribe anytime.
LeadCaptureSection
src/components/LeadCaptureSection.astro A/B-tested two-column lead capture with PDF preview mockup. PostHog feature flag homepage-lead-magnet-variant selects the active variant; defaults to drift-checklist.
Got drift?
Get the checklist. 20 warning signs to spot in your next code review.
No spam. Unsubscribe anytime.
Data Visualization
Report widgets from @buoy-design/plumb. Used in the Buoy dashboard, Ask Buoy reports, and PR comments.
SeverityBadge
@buoy-design/plumb Colored pill with status dot. Used in table cells, timeline events, and inline mentions.
StatCard
@buoy-design/plumb Metric card with large value, label, and optional change indicator. Variant adds left border color.
TrendSpark
@buoy-design/plumb Stat card with inline SVG sparkline. Renders a polyline from the data array.
ScoreGauge
@buoy-design/plumb Semi-circle SVG arc gauge. Auto-colors by percentage: 0-30% critical, 30-60% warning, 60-100% success.
DriftBreakdown
@buoy-design/plumb Pure CSS horizontal bar chart for drift type distribution. Colors are hardcoded per drift type.
DataTable
@buoy-design/plumb Data table with typed cell renderers (severity, bar, filePath, number, delta), optional sort, and expand-to-show-all.
| File | Severity | Issues | Change |
|---|---|---|---|
| Header/Header.module.css | error | +3 | |
| Card/Card.tsx | warning | -2 | |
| Button/Button.module.css | info | 0 | |
| layouts/MainLayout.astro | warning | +1 | |
ComparisonCard
@buoy-design/plumb Before/after comparison. Single-metric mode shows large values with arrow. Multi-metric mode renders a compact table with delta pills.
| Metric | Last Week | This Week | Change |
|---|---|---|---|
| Total Issues | 54 | 42 | -22.2% |
| Critical | 9 | 7 | -22.2% |
| Token Coverage | 82% | 87% | +6.1% |
Timeline
@buoy-design/plumb Vertical timeline with colored dots, PR-aware fields, severity badges, and impact indicators.
Heatmap
@buoy-design/plumb 2D grid heatmap. Groups data by xKey (columns) and yKey (rows). Rows sorted by total descending. Buoy orange color scale.
MetricGrid
@buoy-design/plumb CSS grid wrapper for StatCards. Configurable column count.
VerificationBadge
@buoy-design/plumb Shows data verification status. Green badges for confirmed values, amber for unverified. Tooltip explains methodology.
LineChart
@buoy-design/plumb Multi-series line chart built on Recharts. Themed with design tokens, responsive container, and custom tooltip.
AreaChart
@buoy-design/plumb Gradient-filled area chart with optional stacking. Linear gradient fades from 40% opacity to transparent.
BarChart
@buoy-design/plumb Vertical or horizontal bar chart. Top-rounded bars with chart token colors.
PieChart
@buoy-design/plumb Donut chart with legend. Inner radius creates the donut hole; padding angle separates slices.
SpiderChart
@buoy-design/plumb Radar/spider chart for multi-axis comparison. Shows current vs target across quality dimensions like coverage, consistency, and adoption.
Treemap
@buoy-design/plumb Treemap for hierarchical data sized by value. Shows component distributions, file sizes, or category breakdowns as nested rectangles.
FunnelChart
@buoy-design/plumb Funnel chart for progressive narrowing stages. Use for issue resolution pipelines or conversion flows.
ScatterChart
@buoy-design/plumb Scatter plot for showing correlation between two numeric variables. Use for complexity vs drift count, size vs issues.
WaterfallChart
@buoy-design/plumb Waterfall chart showing cumulative effect of sequential positive and negative values. Last item treated as the total.
StackedBarChart
@buoy-design/plumb Stacked bar chart for comparing category breakdowns across groups. Use for issues by severity per week or drift by type per file.
This page is the test
This page is built to be checked with Buoy. Point the CLI at the live URL and see Buoy score a real design system.
npx ahoybuoy@0.3.38 show health buoy.design/ds.astro