@govhub/ui
v0.1.0
Published
GovHub Design System — components and tokens
Readme
@govhub/ui
GovHub Design System — a dark-theme-first, data-dense React component library and token system for AI-forward GovTech products. 78 components across 8 categories, a two-layer CSS token system, and a Lucide-based icon set.
Operational, intelligence-grade, calm under density. A near-black slate canvas with crisp panels, federal-blue actions, and saturated semantic accents. Inter only. No emoji.
Install
npm install @govhub/uireact and react-dom are peer dependencies (>=18) — install them in your app if
you haven't already.
Quick start
Import the stylesheet once at your app's entry point, then use components anywhere:
import '@govhub/ui/styles.css';
import { Button, Table, StatusPill, Icon } from '@govhub/ui';
export function Toolbar() {
return (
<div style={{ display: 'flex', gap: 8 }}>
<Button variant="primary" leadingIcon="plus">New pursuit</Button>
<Button variant="secondary" leadingIcon="download">Export</Button>
</div>
);
}Styling & theming
@govhub/ui/styles.css is required — it loads the design tokens (CSS custom
properties), the Inter @font-face declarations, and base resets. Components style
themselves entirely through semantic tokens (var(--bg-surface), var(--text-primary),
var(--radius-lg), …), so without the stylesheet they render unstyled.
- Dark by default. Opt into light mode by setting
data-theme="light"on a root element:<html data-theme="light"> - Theme by overriding tokens. Because everything resolves through the semantic layer, you can retheme the system by overriding custom properties in your own CSS — never reach for a primitive hue directly.
- Granular token imports are available if you don't want the full bundle:
import '@govhub/ui/tokens/fig-tokens.css'; // primitives + semantic + spacing + radius import '@govhub/ui/tokens/typography.css'; // type scale + .text-* utilities
The Inter font files ship with the package (assets/fonts/) and are referenced by
tokens/fonts.css. If you'd rather supply Inter yourself (e.g. via @fontsource/inter or
a CDN), you can skip styles.css and import only the token files you need.
What's included
import { … } from '@govhub/ui'
| Category | Components |
| --- | --- |
| Actions | Button, IconButton, FAB |
| Forms | Input, Textarea, Select, Checkbox, Radio, RadioGroup, Switch, SearchInput, OTPInput, EditableField |
| Data display | Avatar, Badge, Card, StatCard, KPICard, ScoreBar, ProgressBar, Tag, Table, DescriptionList, CollapsiblePanel |
| Status | StatusPill, PriorityBadge, DeadlineChip, AgentStatusChip, ParseStatusBadge |
| Navigation | NavItem, Tabs, Pagination, Breadcrumbs, Stepper, SectionHeader, WizardFooter |
| Feedback | Toast, Dialog, Drawer, Menu, Tooltip, Banner, EmptyState, Skeleton, SkeletonText |
| Charts | BarChart, StackedBarChart, LineChart, Sparkline, DonutChart, GaugeChart, RadialProgress, FunnelChart, RadarChart, Heatmap |
| Domain (GovCon composites) | OpportunityCard, StageColumn, AgencyCard, RecommendationCard, AIReasoning, QualificationCriterion, CitationBadge, DetailHeader, NotificationItem, TimelineEntry, FileCard, TaskCard, IntegrationCard, BriefingCard, InsightCard, CompetitorCard, AgreementStatusCard, ReportCard, PastPerformanceCard, CapabilityGapItem, AgencySpendingCard |
Icons
A Lucide-based icon set is bundled and renders with currentColor:
import { Icon, ICON_NAMES } from '@govhub/ui';
<Icon name="radar" size={18} />Names are clean kebab-case ("radar", "file-text", "circle-check"). ICON_NAMES
lists every available glyph. Recolour with CSS color, size with the size prop.
Formats & TypeScript
Ships CJS (dist/index.js), ESM (dist/index.mjs), and bundled type
declarations (dist/index.d.ts). Types for Icon are fully typed; other component prop
types are inferred from source.
Design language
Built for high-information-density GovCon workflows — opportunity discovery, agency intelligence, fit scoring and capture pipelines.
- Colour is functional, not decorative. Each status owns a bold fill, a subtle wash, a border and a text colour: success = emerald, warning = amber, danger = red, info = blue. Priority ramps high → medium → low; fit scores band ≥75 / ≥50 / else.
- Type: Inter only, four weights. A tight ramp — headings top out at 24px, body sits at 14–16px, metadata at 12/11px, eyebrows at 10px uppercase. Tabular figures for numbers.
- Spacing: 4px base unit; dense work leans on the 4–16px steps.
- Surfaces: depth comes from stacking dark surfaces, not shadows. Hairline borders, moderate corners (cards 12px, controls 8px). The focus ring is the one loud effect.
- Motion: quick and functional (100–160ms); respects
prefers-reduced-motion.
License
UNLICENSED (proprietary) — update the license field in package.json and this section
before distributing outside your organization.