Velais UI Design Skill

Single source of truth for all Velais-branded internal UI products. When starting a new Velais dashboard, tool, or client-facing app, invoke this skill first.

Quick Reference

Before building anything, read the relevant reference file:

Task	Reference File
Color tokens, palette, status colors	references/color-system.md ← start here
Font loading, typography rules	references/typography.md
GSAP setup, useCascadeAnimation	references/animation-system.md
shadcn setup, Tailwind 4, component patterns	references/component-patterns.md
Full-screen loading overlay	references/loader-component.md
Branded login / sign-in page	references/login-page.md

Complementary Skills

Skill	When to also invoke
/gsap-animations	Building any new animation beyond the Velais cascade pattern
/velais-brand-guidelines	Creating documents, presentations, or marketing materials
/react-best-practices	Performance optimization, memoization, code splitting
shadcn MCP (mcp__shadcn__*)	Adding or auditing shadcn/ui components

Overview

Tech stack: React 19 · TypeScript · Vite · Tailwind CSS 4 · TanStack React Query · GSAP · Hono backend · Bun runtime

Design philosophy:

• Dark-first — deep navy/off-black backgrounds; brand blues for text, borders, and interactive elements only
• Monochromatic blue palette — five blues from #aecceb (soft-sky) to #0b1b3e (midnight-blue) plus one muted burgundy for errors
• Purposeful motion — GSAP for all animation; CSS-only transitions only for hover micro-interactions (≤ 200ms)
• Heading vs body font discipline — Onsite Extended for headings, Host Grotesk for everything else

Core Design Rules

These rules apply in every Velais UI project:

1. Colors: Always use CSS variables (var(--color-*)) or Tailwind semantic utilities. Never hardcode hex in component files.
2. Typography: Use font-heading (Onsite Extended) only for headings. Use font-body (Host Grotesk) for all other text.
3. GSAP imports: Always import gsap and useGSAP from @/lib/gsap.ts (the singleton). Never import directly from gsap or @gsap/react.
4. GSAP compositing: Add [data-gsap] { will-change: transform, opacity; } globally in CSS. Mark animated elements with data-gsap="<role>".
5. Animated elements that start hidden: Use Tailwind invisible class + GSAP autoAlpha to reveal. Never use opacity-0 for GSAP-driven reveals.
6. shadcn style: Always initialize with --style new-york and --base-color neutral. Set cssVariables: true.
7. Path aliases: Configure @/* → ./src/* and @shared/* → ./shared/* in both tsconfig.json and vite.config.ts.

New Project Setup Checklist

Follow this checklist when starting a new Velais UI product:

1. Scaffold

bun create vite@latest my-app -- --template react-ts
cd my-app
bun install

2. Install core dependencies

bun add gsap @gsap/react @tanstack/react-query clsx tailwind-merge lucide-react
bun add -d @tailwindcss/vite tailwindcss typescript @types/react @types/react-dom

3. Configure Tailwind CSS 4

Remove tailwind.config.ts — Tailwind 4 is configured via @theme in CSS.

In vite.config.ts:

import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: { "@": "/src", "@shared": "/shared" },
  },
});

In src/index.css, add the full @theme block from references/color-system.md.

4. Initialize shadcn/ui

bunx --bun shadcn@latest init
# Style: New York
# Base color: Neutral
# CSS variables: Yes

5. Copy font files

Copy assets/fonts/OnsiteExtended-Regular.woff2 and .woff to src/fonts/.

Add @font-face declaration from references/typography.md to src/index.css.

6. Add favicon tags

Copy assets/favicon/ to public/. Add <link> tags from assets/templates/index-head.html to index.html.

7. Create GSAP singleton

Copy assets/templates/gsap.ts to src/lib/gsap.ts.

8. Create logo constants

Copy assets/templates/logo.ts to src/lib/logo.ts. Copy assets/logo/logo-symbol.svg to src/assets/.

9. Add global CSS rules

In src/index.css:

[data-gsap] { will-change: transform, opacity; }
.kanban-card { content-visibility: auto; contain-intrinsic-size: 0 80px; }

10. Copy Loader and LoginPage

See references/loader-component.md and references/login-page.md for full verbatim implementations.

Reusable Components

Loader

Full-screen branded loading overlay with three SVG layers (ghost, fill, shimmer) and a diagonal progress fill driven by GSAP. Accepts dataReady and onComplete props. See references/loader-component.md for the complete verbatim implementation.

LoginPage

Branded sign-in page with a sequential GSAP timeline entry (logo → wordmark → divider → subtitle → button → footer). Uses data-login="<role>" attributes and Tailwind invisible

• GSAP autoAlpha pattern. Accepts onSignIn prop. See references/login-page.md for the complete verbatim implementation.