nexus-design-system

name	nexus-design-system
effort	high
description	NEXUS ANTIGRAVITY UI/UX Design System — the definitive guide for all visual work on the NEXUS healthcare SaaS. Use this skill whenever the user asks to: improve or redesign any page or component, create new UI components, update visual design, fix styling inconsistencies, add dark mode support, improve responsiveness, enhance animations/transitions, or do any UI/UX work on the NEXUS app. Also trigger when the user mentions 'design', 'visual', 'UI', 'UX', 'estilo', 'layout', 'tema', 'dark mode', 'responsivo', 'componente', 'tela', 'página', 'redesign', 'melhorar visual', or asks to make something 'mais bonito' or 'mais moderno'. If the user is working in the NEXUS codebase and the task involves anything visual, use this skill.

NEXUS Design System

You are working on NEXUS ANTIGRAVITY, a healthcare SaaS with a premium clinical aesthetic. This skill ensures every UI change follows the established design language — consistent, accessible, dark-mode-ready, and mobile-first.

How to use this skill

When the user requests visual work, follow this methodology:

1. Read first — Always read the target component/page code before making changes
2. Audit — Compare what exists against the tokens and patterns in this skill
3. Fix inconsistencies — Apply NEXUS tokens (colors, shadows, radius, spacing)
4. Ensure completeness — Dark mode, responsive, accessible, loading/empty/error states
5. Use existing components — Check src/ui/components/common/ before creating anything new
6. Micro-interactions — Add hover effects, transitions, and focus states where missing

For detailed reference, read:

• references/tokens.md — All design tokens (colors, shadows, typography, spacing)
• references/components.md — Component catalog with APIs and usage examples
• references/patterns.md — Page layouts, responsive patterns, and visual conventions

Core Design Principles

1. Corporate Medical Aesthetic

The NEXUS visual identity is clean, professional, and clinical. Think premium hospital software — not playful, not casual. This means:

• No emojis anywhere in the UI
• Muted backgrounds (Ice #F6F8FA light, Navy #0A0F24 dark)
• Teal as the singular accent color for CTAs and active states
• Generous whitespace and breathing room between elements
• Subtle shadows instead of bold borders

2. The NEXUS Teal

Teal #00C2CB is the brand's signature. Use it for:

• Primary buttons and CTAs (gradient: from-[#00C2CB] to-[#008B94])
• Active/selected states (tabs, sidebar items)
• Focus rings (focus:ring-[#00C2CB]/50)
• Accent shadows (shadow-teal)
• Links and interactive text

Use teal sparingly — it's powerful because it's concentrated. If everything is teal, nothing stands out.

3. Dark Mode is Not Optional

Every element must have dark mode support. The NEXUS dark theme uses deep navy tones:

• Background: #0A0F24 (dark-bg)
• Cards: #12182F (dark-card)
• Borders: #232942 (dark-border)
• Text: White/gray-300 for readability

Always add dark: prefix classes alongside light classes. If you're writing bg-white, also write dark:bg-[#12182F]. If you're writing text-gray-700, also write dark:text-gray-300.

4. Mobile-First, Always

Design for mobile screens first, then enhance for larger screens:

• Touch targets: minimum 44px (WCAG 2.1 AA)
• Responsive grids: grid-cols-1 md:grid-cols-2 lg:grid-cols-3
• Typography scales: text-xl md:text-2xl lg:text-3xl
• Padding adapts: px-4 md:px-6 lg:px-8
• Test at 375px, 768px, and 1280px widths

Quick Reference — Design Tokens

Colors

Token	Value	Usage
nexus-navy	#0A0F24	Primary text, dark backgrounds
nexus-teal	#00C2CB	CTAs, active states, accent
nexus-teal-dark	#00A3AB	Hover states on teal elements
nexus-ice	#F6F8FA	Light mode backgrounds
nexus-graphite	#3A3F58	Secondary text, subtle borders
nexus-active	#28C76F	Success, active, completed
nexus-alert	#FF4D4F	Error, danger, cancelled
nexus-warning	#FF9F43	Warning, pending states

Module Accent Colors

Each clinical module has its own accent color for header gradients and icons:

Module	Color	Hex
EndoInject	Teal	#00C2CB
iMeddis	Purple	#8B5CF6
LabPro	Amber	#F59E0B
BodyScan	Indigo	#6366F1
Lifestyle	Emerald	#10B981
Pharma	Teal	#14B8A6

Shadows

Always use NEXUS shadow classes — never arbitrary shadow-[...] values:

Class	Effect	When to use
shadow-nexus-sm	0 2px 12px rgba(0,0,0,0.04)	Subtle cards, dropdowns
shadow-nexus	0 4px 20px rgba(0,0,0,0.06)	Standard cards, panels
shadow-nexus-lg	0 8px 32px rgba(0,0,0,0.08)	Modals, elevated elements
shadow-teal	0 4px 14px rgba(0,194,203,0.20)	Teal buttons, active elements

Border Radius

Element	Class	Size
Small elements (badges, pills)	rounded-lg	8px
Standard (buttons, inputs)	rounded-xl	12px
Cards, panels	rounded-2xl	16px
NEXUS token	rounded-nexus	12px

Typography

Level	Classes	Usage
Metric values	text-3xl font-bold	KPI numbers, big stats
Page titles	text-xl md:text-2xl lg:text-3xl font-bold	H1 of pages
Section headings	text-lg font-bold	Card headers, sections
Body text	text-sm font-medium	Regular content
Labels	text-xs font-medium text-gray-500	Form labels, timestamps
Muted/helper	text-xs text-gray-400	Helper text, descriptions

Transitions

Standard transition for all interactive elements:

transition-all duration-200

Sidebar and overlays use longer durations:

duration-300 ease-[cubic-bezier(0.4,0,0.2,1)]

Anti-Patterns — Things to NEVER Do

These rules exist because breaking them causes visual inconsistency, dark mode bugs, or accessibility failures:

1. Arbitrary colors — Don't use bg-blue-500 or text-[#random]. Use NEXUS palette tokens.
2. Emojis in UI — Corporate medical product. Use Lucide icons instead.
3. Light-only colors — Every bg-white needs dark:bg-[#12182F]. Every text-gray-700 needs dark:text-gray-300.
4. Reinventing components — 21 components exist in src/ui/components/common/. Check there first.
5. Non-standard radius — Use rounded-lg, rounded-xl, rounded-2xl, or rounded-nexus. Nothing else.
6. Missing states — Every data-fetching view needs loading (Skeleton), empty (EmptyState), and error states.
7. Inline styles — Use Tailwind classes. No style={{}} except for truly dynamic values.
8. Arbitrary shadows — Use shadow-nexus-* classes only.
9. Breaking component APIs — Don't add required props to existing components without checking all usages.
10. Skipping focus states — Every interactive element needs focus:ring-2 focus:ring-[#00C2CB]/50.

Component Usage Guide (Quick)

Before creating any UI element, check if it already exists:

Need	Use this component	Location
Action button	<Button variant="primary">	common/Button.tsx
Content container	<Card>	common/Card.tsx
Text field	<Input label="..." />	common/Input.tsx
Dropdown	<Select options={...} />	common/Select.tsx
Status indicator	<StatusBadge status="active" />	common/StatusBadge.tsx
KPI display	<MetricCard title="..." value={...} />	common/MetricCard.tsx
Page header	<ModuleHeader title="..." icon={...} />	common/ModuleHeader.tsx
Tab selector	<TabNav tabs={...} />	common/TabNav.tsx
Empty data	<EmptyState icon={...} title="..." />	common/EmptyState.tsx
Loading	<LoadingSpinner /> or <Skeleton />	common/LoadingSpinner.tsx, common/Skeleton.tsx
Confirmation	<ConfirmDialog intent="danger" />	common/ConfirmDialog.tsx
Progress	<ProgressBar value={75} />	common/ProgressBar.tsx
User image	<Avatar name="..." />	common/Avatar.tsx
Pages	<Pagination />	common/Pagination.tsx

For full component APIs and props, read references/components.md.

Tech Stack Context

• React 18 + TypeScript strict mode
• Tailwind CSS with custom config (tailwind.config.js)
• Lucide React for icons (300+ available)
• Recharts for data visualization
• Framer Motion for complex animations (available but most use CSS transitions)
• Zustand for state management
• No UI framework — all components are custom Tailwind
• CSS custom properties for theme switching (--nexus-bg, --nexus-card, etc.)
• Font loading: Inter (Google Fonts) + JetBrains Mono

When Improving an Existing Page

Follow this checklist in order:

1. Read the component code completely
2. List all visual inconsistencies (wrong colors, missing dark mode, arbitrary shadows, etc.)
3. Check if it uses common components or has inline implementations
4. Apply fixes in this priority:
   • Replace inline UI with common components
   • Fix colors to use NEXUS tokens
   • Add missing dark: classes
   • Fix border radius to standard values
   • Replace arbitrary shadows with shadow-nexus-*
   • Add missing transitions (transition-all duration-200)
   • Add missing focus states
   • Ensure responsive grid patterns
   • Add missing loading/empty/error states
5. Test dark mode toggle mentally (every color has a dark variant?)
6. Test mobile mentally (does it stack properly? Touch targets 44px?)

When Creating a New Component

1. Check src/ui/components/common/ — does something similar exist?
2. If yes, extend or compose existing components
3. If no, follow this template:

import React from 'react';

interface MyComponentProps {
  // Required props first, optional after
}

export function MyComponent({ ...props }: MyComponentProps) {
  return (
    <div className="
      bg-white dark:bg-[#12182F]
      border border-gray-100 dark:border-[#232942]
      rounded-2xl shadow-nexus-sm
      p-4 md:p-6
      transition-all duration-200
    ">
      {/* Content */}
    </div>
  );
}

Key rules for new components:

• Always support dark mode from the start
• Use NEXUS tokens for all visual properties
• Accept className prop for composition
• Use TypeScript strict types
• Export as named export (not default)