Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Tailwind CSS v4 Guidelines
Version
This project uses Tailwind CSS v4. The v4 API is substantially different from v3:
- Configuration is done via CSS
@themeinfrontend/src/index.cssinstead of a Tailwind config file - The project has no Tailwind config file (
components.jsonsetstailwind.configto an empty string) - do not create one - Use
@import "tailwindcss"in the main CSS entry point - Utility classes are the same as v3 in most cases
Token References
Design tokens are defined in frontend/src/index.css and listed in docs/architecture/frontend/DESIGN_SYSTEM.md. Use them through their utility class names. Never use hex values or Tailwind palette colours (bg-red-500, text-pink-600) in components.
Common token utilities:
bg-surface/text-ink- page background and main textbg-surface-raised- cards and panelsbg-surface-sunken/text-ink-muted/text-ink-faint- wells and secondary textborder-line- hairline borders;border-line-control- control bordersbg-brand/text-on-brand- primary action;text-brand-text- red as textbg-danger-soft/text-danger, plussuccess,warning,info- status
The shadcn names (bg-background, text-muted-foreground, bg-primary) still work and map onto the same tokens.
Layout
Page wrapper
The app shell already pads and centres the content column. Pages start with a flex column:
<div className="flex flex-col gap-6">
<PageHeader title="Videos" description="..." actions={...} />
{/* sections */}
</div>
Grid layouts
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
{/* stat cards */}
</div>
Flex rows
<div className="flex items-center gap-2">
{/* icon + label */}
</div>
Spacing System
Use the spacing scale consistently. Common patterns in this project:
gap-6- between page sections (gap-8on pages with large sections)gap-3- between metric boxes in a gridgap-4- between boxes in a gridpx-5 py-4- inside aSurfaceBox(built in)gap-2- inline icon and label- Prefer
gap-*on flex and grid overspace-y-*
Typography
Use PageHeader for the page title and SectionHeader or a SurfaceBox title for sections. When writing type directly:
<h1 className="font-heading text-page-title font-semibold">Page title</h1>
<h2 className="font-heading text-section font-semibold">Section</h2>
<p className="text-small text-ink-muted">Secondary info</p>
<span className="font-mono text-caption tabular-nums">42</span>
Avoid using text-xs for anything the user needs to read comfortably. Use text-sm as the minimum for content.
Responsive
Mobile-first. Most pages in this app are designed primarily for desktop (analytics dashboards), but keep them usable on mobile:
- Use
grid-cols-1 md:grid-cols-2 lg:grid-cols-4for stat card rows - Use
overflow-x-autoon table wrappers - Use
hidden md:flexto hide elements that don't fit on mobile
Dark Mode
Light and dark values are both defined as tokens, so token utilities switch automatically. Do not use dark: variants for colour. The one sanctioned use of dark: is swapping the logo file in components/brand/Logo.tsx.
If you need to add a custom dark-mode variant for non-token colors, add a CSS custom property to the @theme block instead.
The cn() Utility
Use cn() (from @/lib/utils) for conditional class merging:
import { cn } from '@/lib/utils';
<div className={cn(
'base-class',
isActive && 'bg-primary text-primary-foreground',
className // allow parent to override
)} />
Never use template literals for conditional classes - they won't be properly merged and can produce duplicate or conflicting utilities.
What Not To Do
- Do not use
style={{}}for values that can be expressed as Tailwind utilities - Do not hardcode colors in class names (
text-[#ff0000]) - use design token utilities - Do not use
!important(!text-red-500) unless debugging a specificity conflict - Do not create a Tailwind config file - configuration lives in the CSS
@themeblock in v4 - Do not use
dark:prefix variants - theme is token-based, not class-based