Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
shadcn/ui Standards
Configuration
// frontend/components.json (excerpt)
{
"style": "base-nova",
"rsc": false,
"tsx": true,
"tailwind": { "config": "", "css": "src/index.css", "cssVariables": true },
"aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui" }
}
Style: base-nova. CSS variables: enabled. TypeScript: tsx: true, so the CLI writes .tsx files. tailwind.config is empty because Tailwind v4 is configured in src/index.css.
Import Pattern
Always import from the local @/components/ui/ path:
import { Button } from '@/components/ui/button';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
import { Badge } from '@/components/ui/badge';
Never import from shadcn/ui directly - the components are copied into the project.
Adding a New Component
cd frontend
npx shadcn add <component-name>
Run the CLI from frontend/, where components.json lives. The shadcn CLI is a dependency of the frontend workspace, so npx shadcn uses the version pinned in the root package-lock.json. If the CLI installs npm packages for a component, check afterwards that no frontend/package-lock.json was created; the root lockfile is the only one, and a stray workspace lockfile should be deleted and npm install run again at the root.
This copies the component source into frontend/src/components/ui/ as a .tsx file, following the official base-nova TypeScript sources. Run npm run typecheck from the root afterwards.
Composition Rules
shadcn components are composed using their named export variants. Read the component file in frontend/src/components/ui/ to understand the available props before using them.
// Tooltip composition: the trigger renders the button, the content is the label
<Tooltip>
<TooltipTrigger render={<Button variant="ghost" size="icon-xs" aria-label="Refresh" />}>
<RefreshCw />
</TooltipTrigger>
<TooltipContent>Refresh</TooltipContent>
</Tooltip>
Only the components the app uses are kept in components/ui/. Add one with the CLI when a feature needs it, and delete it when the last use goes. Grouped content uses SurfaceBox and labelled fields use FieldRow (DESIGN_SYSTEM.md), not Card or Label.
Common Components in Use
| Component | Import | Use case |
|---|---|---|
Button |
@/components/ui/button |
All action buttons; use variant prop: default, outline, ghost, destructive |
Badge |
@/components/ui/badge |
Status labels, platform tags |
Avatar |
@/components/ui/avatar |
Channel/account avatars |
Table, TableHeader, etc. |
@/components/ui/table |
Data tables |
Tabs, TabsList, TabsTrigger, TabsContent |
@/components/ui/tabs |
View switching |
Dialog, DialogContent, etc. |
@/components/ui/dialog |
Modals |
Select, SelectTrigger, etc. |
@/components/ui/select |
Dropdown selects |
Tooltip, TooltipContent, etc. |
@/components/ui/tooltip |
Hover tooltips |
Skeleton |
@/components/ui/skeleton |
Loading placeholders |
Alert, AlertTitle, AlertDescription |
@/components/ui/alert |
Info/warning/error banners |
Input |
@/components/ui/input |
Text inputs |
cn() Utility
Always use cn() from @/lib/utils to combine class names - it handles conditional classes and tailwind-merge conflicts:
import { cn } from '@/lib/utils';
<div className={cn('base-class', isActive && 'active-class', className)}>
Shared components
Project components in frontend/src/components/ sit on top of the shadcn primitives. Use them before composing primitives by hand. MetricBox is the KPI tile used across analytics pages:
import MetricBox from '@/components/MetricBox';
<MetricBox
icon={<Eye />}
label="Total views"
value={fmtNum(analytics.totalViews)}
subtitle="Lifetime channel views"
highlight
/>
The full list (PageHeader, SurfaceBox, ConfirmDialog, FilterChips, and others) is in docs/architecture/frontend/DESIGN_SYSTEM.md.
The shadcn primitives in components/ui/ are restyled onto the design tokens. Keep that styling when regenerating a primitive with the shadcn CLI: diff the new file against the current one before overwriting.
Theme
The project uses next-themes with attribute="class". Dark mode is applied by adding the dark class to <html>. All shadcn components respond to this automatically via CSS variables defined in frontend/src/index.css.
Do not hardcode colors in components - use Tailwind semantic classes (text-muted-foreground, bg-card, border-border, etc.) that reference CSS variables.