rvenkat design system

Tokens, a Tailwind v4 + shadcn/ui theme, and the rules for using them. Every text colour pair is checked at WCAG AA in CI, in light and dark.

Use it

In a Next.js or Vite app with Tailwind v4 and shadcn/ui, install the theme from this site:

npx shadcn@latest add https://design-system.apps.rvenkat.com/r/theme.json

Or copy theme.css next to your global CSS and import it after Tailwind:

@import "tailwindcss";
@import "./theme.css";

Then use shadcn/ui components as they are. The tokens: tokens.json. Source: platform/design-system.

Colour

Neutral zinc surfaces and one blue for action. Status colours are for status only, and always come with an icon or a word, never colour alone.

Type

The system font: SF Pro on Apple devices, Segoe UI on Windows, Roboto on Android. Nothing to download, so text shows instantly. Body text is 16px with 1.5 line height; lines stay under about 70 characters.

Page title3xl / 700
Section heading2xl / 600
Card titlelg / 600
Body text for reading.base / 400
Labels and buttonssm / 500
Captions and table metaxs / 400
mono: code, ids, hashesfont-mono

Components

Buttons

One primary button per screen. Destructive actions are red, set apart, and ask before they act. Tab through them: every control shows a focus ring.

Form field

Lower case, becomes <name>.apps.rvenkat.com

Labels above fields, always visible. Help text under the field. Errors say what is wrong and how to fix it, next to the field.

Status

Healthy Degraded Down Draft

Alert

Staging updated. Commit 11dd6305 passed end-to-end tests and is waiting for production.

Table

ServiceEnvironmentStatusp95 latency
agent-serviceproductionHealthy182 ms
agent-servicestagingHealthy96 ms

Numbers in tables use tabular figures and align right.

Rules

  • Use tokens, never raw hex values, in components. Dark mode then comes for free.
  • Spacing on a 4px grid: 4, 8, 12, 16, 24, 32, 48. Radius 8px for controls, 10px for cards.
  • Touch targets at least 40px tall on desktop, 44px on mobile. 8px between targets.
  • Icons: Lucide, 16px in text, 20px in buttons, 2px stroke. No emoji as icons.
  • Motion 150 to 300ms, ease-out to enter, faster to leave, only on colour, opacity and transform. Reduced motion is honoured by the theme.
  • Never remove focus rings. Every icon-only button has an aria-label.
  • AI interfaces: show progress within 300ms (streaming text or a skeleton), show which model answered, and let people stop a run.
  • Check new colour pairs with python3 scripts/check_contrast.py; CI does it on every change.