1. Core Principles

• Typography over Decoration: Rely on font weight, size, and color contrast to establish hierarchy rather than heavy shadows or background fills.
• Monochrome + One: The interface should be 90% grayscale (neutrals). The accent color (Purple) is reserved strictly for primary actions, active states, and interactive affordances.
• Subtle Containment: Use delicate 1px borders to separate content instead of heavy drop shadows or background offsets.
• Smooth, Physical Motion: Animations should feel like sliding paper, not bouncing rubber. Use ease-out curves and tight spring physics.

3. Typography

The interface relies on two font families to separate structural application text from data/content.

• Font Heading (font-heading): Plus Jakarta Sans
  • Usage: Page titles, large numbers, brand elements.
  • Tracking (Letter-spacing): Tight (-0.02em to -0.05em).
• Font Sans (font-sans): Inter
  • Usage: Body copy, input text, sidebars, tables, buttons.
  • Tracking (Letter-spacing): Normal (0em).
• Font Mono (font-mono): Geist Mono or JetBrains Mono
  • Usage: IDs, keys, JSON payloads, URLs.

Sizing Scale

• Micro (10px / 0.625rem): Uppercase tracking labels (uppercase tracking-wider).
• Small (12px / 0.75rem): Standard labels, helper text, sidebar child items.
• Base (14px / 0.875rem): Standard body text, button text, input text.
• Heading 3 (18px / 1.125rem): Card titles, section headers.
• Heading 2 (24px / 1.5rem): Page titles.

4. Iconography (lucide-react)

Strict rules apply to icon usage to prevent the UI from looking cluttered or "cartoony."

• Stroke Width: Always strokeWidth={2}. Do not mix stroke weights.
• Sizing Matrix:
  • 14px (w-3.5 h-3.5): Inline with Small or Base text (e.g., inside buttons, nested sidebar items, micro-labels).
  • 16px (w-4 h-4): Standard standalone icons (e.g., icon-only buttons, top-level sidebar items).
  • 20px (w-5 h-5): Section headers or modal headers.
• Coloring: * Icons should default to text.secondary.
  • Never use text.primary for icons unless it's a primary brand anchor.
  • Active/Selected state icons use accent.primary.

5. Motion & Physics Tokens

Animations must be non-blocking, fast, and mimic physical interfaces.

1. The "SaaS Spring" (Layout & Tab Sliding)

Used for sliding indicators, expanding sidebars, and moving elements.

• Type: Spring
• Stiffness: 500
• Damping: 35
• Mass: 1

2. The "Quick Fade" (Opacities & Modals)

Used for hovering, opening dropdowns, and switching tabs.

• Type: Tween
• Easing: easeOut ([0, 0, 0.2, 1])
• Duration: 150ms to 250ms (0.15s - 0.25s)

6. Component Blueprints

A. Surfaces (Cards & Modals)

• Border Radius: 6px (rounded-md). Do not use heavily rounded corners (rounded-xl or rounded-2xl).
• Borders: 1px solid border.default.
• Shadow: box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05) (A bare minimum shadow, just enough to lift off the canvas).
• Padding: Standardize on 24px (p-6) or 32px (p-8) for card bodies.

B. Navigation (Nested Sidebar)

• Hierarchy Indentation: 22px left padding for child items.
• Guide Lines: A 1px vertical line (border.default) positioned absolute left to connect child items to parents.
• Active State: Background accent.subtle, Text accent.primary, Icon accent.primary. Font weight increases to Medium (500).

C. Inputs & Controls

• Height: 40px standard (py-2.5 px-4).
• Idle State: Background background.subtle, Border border.default.
• Focus State: Background background.surface (White), Border accent.primary, plus a 4px translucent ring (rgba(124, 58, 237, 0.1)).
• Labels: Above the input. 12px (text-xs), Medium weight, uppercase tracking-wider, text.secondary.

D. Buttons

• Primary: Background accent.primary, Text White. Hover: Darken background by 10%.
• Ghost/Secondary: Background transparent, Text text.secondary. Hover: Background background.subtle, Text text.primary.
• Destructive Ghost: Background transparent, Text text.tertiary. Hover: Background Danger Subtle, Text Danger.

E. Data Tables (Proactive)

• Header Row: Background background.subtle, Border Bottom 1px border.default. Text 12px Medium uppercase.
• Data Rows: Background background.surface. Border Bottom 1px border.subtle. Text 14px.
• Hover: Entire row background shifts to background.subtle.

F. Modals / Dialogs (Proactive)

• Overlay: rgba(0,0,0,0.4) (Dark mode: rgba(0,0,0,0.6)) with a 4px background blur (backdrop-blur-sm).
• Entrance: Scale up from 0.95 to 1.0, Y-axis shift from 10px to 0px, Opacity 0 to 1. Duration 300ms, Spring physics.
• Header: Border bottom 1px border.subtle. Close button (X icon) strictly top-right.

G. Toasts / Notifications (Proactive)

• Placement: Bottom-Right.
• Style: Inverse of current theme (e.g., dark toast in light mode) for high visibility.
• Padding: 12px vertical, 16px horizontal.
• Border Radius: 6px.