Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

4.6 KB
Raw Blame

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.