282 lines
7.8 KiB
TypeScript
282 lines
7.8 KiB
TypeScript
'use client';
|
|
|
|
/**
|
|
* LinkCard Component
|
|
*
|
|
* An interactive navigation card for guiding users to related documentation pages.
|
|
* Uses color accents and hover effects to create an engaging, explorable experience.
|
|
*
|
|
* ## Design Principles
|
|
*
|
|
* 1. **Visual Affordance**: Design signals interactivity
|
|
* - Gradient backgrounds hint at clickability
|
|
* - Hover states provide immediate feedback
|
|
* - Cursor changes to pointer on hover
|
|
* - Border transitions guide attention
|
|
*
|
|
* 2. **Semantic Color System**: Accent colors convey meaning
|
|
* - Primary (Purple): Main content, API references
|
|
* - Secondary (Cyan): Supporting content, guides
|
|
* - Success (Green): Getting started, tutorials
|
|
* - Warning (Amber): Important notices, deprecations
|
|
*
|
|
* 3. **Information Hierarchy**: Title dominates, description supports
|
|
* - Large, bold title draws attention
|
|
* - Smaller, muted description provides context
|
|
* - Title color changes on hover for feedback
|
|
* - Clean vertical rhythm (title → description)
|
|
*
|
|
* ## Accent Color Semantics
|
|
*
|
|
* @param {'primary'} primary - Main navigational elements, API documentation
|
|
* - Visual: Purple gradient and border
|
|
* - Psychology: Primary brand, core content, important
|
|
* - Use cases: "API Reference", "Core Concepts", main docs
|
|
* - Gradient: from-purple-500/10
|
|
* - Hover: border-purple-500/40, text-purple-400
|
|
*
|
|
* @param {'secondary'} secondary - Supporting content, guides, tutorials
|
|
* - Visual: Cyan gradient and border
|
|
* - Psychology: Complementary, helpful, educational
|
|
* - Use cases: "Guides", "Tutorials", "Best Practices"
|
|
* - Gradient: from-cyan-500/10
|
|
* - Hover: border-cyan-500/40, text-cyan-400
|
|
*
|
|
* @param {'success'} success - Getting started, quick wins, positive actions
|
|
* - Visual: Green gradient and border
|
|
* - Psychology: Achievement, beginning, growth
|
|
* - Use cases: "Getting Started", "Quick Start", "First Steps"
|
|
* - Gradient: from-green-500/10
|
|
* - Hover: border-green-500/40, text-green-400
|
|
*
|
|
* @param {'warning'} warning - Important notices, cautions, deprecations
|
|
* - Visual: Amber gradient and border
|
|
* - Psychology: Attention, caution, important
|
|
* - Use cases: "Migration Guide", "Breaking Changes", "Deprecations"
|
|
* - Gradient: from-amber-500/10
|
|
* - Hover: border-amber-500/40, text-amber-400
|
|
*
|
|
* ## Interactive States
|
|
*
|
|
* Default State:
|
|
* - Subtle gradient background (from-{color}-500/10)
|
|
* - Muted border (border-slate-700/50)
|
|
* - White title, gray description
|
|
* - Inviting but not demanding attention
|
|
*
|
|
* Hover State:
|
|
* - Border brightens to accent color (/40 opacity)
|
|
* - Title transitions to accent color
|
|
* - Smooth transition (transition-colors)
|
|
* - Clear feedback that element is clickable
|
|
*
|
|
* ## Layout Structure
|
|
*
|
|
* Padding System:
|
|
* - p-5 (20px): Generous padding for comfortable clicking
|
|
* - Creates substantial hit area for accessibility
|
|
* - Provides breathing room for content
|
|
*
|
|
* Border & Radius:
|
|
* - rounded-xl (12px): Modern, friendly appearance
|
|
* - border: Defined structure
|
|
* - Matches other card components in system
|
|
*
|
|
* ## Typography System
|
|
*
|
|
* Title (h3):
|
|
* - text-lg (18px): Large enough to be primary visual element
|
|
* - font-semibold (600): Strong but not overbearing
|
|
* - text-white: Maximum contrast and readability
|
|
* - mb-2 (8px): Separates from description
|
|
* - Transitions to accent color on hover
|
|
*
|
|
* Description (p):
|
|
* - text-sm (14px): Clearly secondary to title
|
|
* - text-gray-400: Muted, supporting role
|
|
* - Provides context without competing with title
|
|
*
|
|
* ## Accessibility Features
|
|
*
|
|
* - Semantic HTML (<a> tag for links)
|
|
* - Proper heading hierarchy (h3 for card titles)
|
|
* - Keyboard accessible (focusable link)
|
|
* - Sufficient color contrast in all states
|
|
* - Large click target (full card clickable)
|
|
* - Clear focus states (browser default + hover)
|
|
* - Descriptive link text (title + description)
|
|
*
|
|
* ## Usage Examples
|
|
*
|
|
* ```tsx
|
|
* // Primary content link
|
|
* <LinkCard
|
|
* href="/docs/api/text-to-image"
|
|
* title="API Reference"
|
|
* description="Explore all available endpoints, parameters, and response formats."
|
|
* accent="primary"
|
|
* />
|
|
*
|
|
* // Getting started
|
|
* <LinkCard
|
|
* href="/docs/quick-start"
|
|
* title="Quick Start"
|
|
* description="Get up and running with Banatie API in 5 minutes."
|
|
* accent="success"
|
|
* />
|
|
*
|
|
* // Supporting guide
|
|
* <LinkCard
|
|
* href="/docs/guides/authentication"
|
|
* title="Authentication Guide"
|
|
* description="Learn about API keys, rate limits, and security best practices."
|
|
* accent="secondary"
|
|
* />
|
|
*
|
|
* // Important notice
|
|
* <LinkCard
|
|
* href="/docs/migration"
|
|
* title="Migration Guide"
|
|
* description="Upgrade to v2 API with this step-by-step migration guide."
|
|
* accent="warning"
|
|
* />
|
|
* ```
|
|
*
|
|
* ## Content Guidelines
|
|
*
|
|
* Title:
|
|
* - 2-5 words ideal
|
|
* - Action-oriented or noun-based
|
|
* - Clear and specific
|
|
* - Sentence case
|
|
* - Examples: "API Reference", "Quick Start", "Authentication Guide"
|
|
*
|
|
* Description:
|
|
* - One sentence (10-20 words)
|
|
* - Explain what user will find/learn
|
|
* - Start with verb (Explore, Learn, Discover)
|
|
* - End with period
|
|
* - Be specific about content
|
|
*
|
|
* Accent Color:
|
|
* - Choose based on content type and importance
|
|
* - Maintain consistency across similar pages
|
|
* - Use primary for most API/core documentation
|
|
* - Reserve warning for truly important notices
|
|
*
|
|
* ## Visual Language
|
|
*
|
|
* The LinkCard system creates:
|
|
* - Intuitive navigation patterns
|
|
* - Clear content categorization through color
|
|
* - Engaging, explorable documentation
|
|
* - Professional yet friendly appearance
|
|
* - Consistent user experience across all docs
|
|
*
|
|
* @component
|
|
* @example
|
|
* <LinkCard
|
|
* href="/docs/api"
|
|
* title="API Reference"
|
|
* description="Complete API documentation"
|
|
* accent="primary"
|
|
* />
|
|
*/
|
|
|
|
/**
|
|
* Accent color determining the card's visual theme
|
|
*/
|
|
export type LinkCardAccent = 'primary' | 'secondary' | 'success' | 'warning';
|
|
|
|
/**
|
|
* Props for the LinkCard component
|
|
*/
|
|
export interface LinkCardProps {
|
|
/** Navigation URL */
|
|
href: string;
|
|
/** Card title (renders as h3) */
|
|
title: string;
|
|
/** Supporting description */
|
|
description: string;
|
|
/** Visual accent color */
|
|
accent: LinkCardAccent;
|
|
/** Optional icon or emoji to display */
|
|
icon?: string;
|
|
/** Optional CSS class name for additional styling */
|
|
className?: string;
|
|
}
|
|
|
|
/**
|
|
* Accent styles mapping color to gradient and hover colors
|
|
*/
|
|
const accentStyles: Record<LinkCardAccent, {
|
|
gradient: string;
|
|
hoverBorder: string;
|
|
hoverText: string;
|
|
}> = {
|
|
primary: {
|
|
gradient: 'from-purple-500/10',
|
|
hoverBorder: 'hover:border-purple-500/40',
|
|
hoverText: 'group-hover:text-purple-400',
|
|
},
|
|
secondary: {
|
|
gradient: 'from-cyan-500/10',
|
|
hoverBorder: 'hover:border-cyan-500/40',
|
|
hoverText: 'group-hover:text-cyan-400',
|
|
},
|
|
success: {
|
|
gradient: 'from-green-500/10',
|
|
hoverBorder: 'hover:border-green-500/40',
|
|
hoverText: 'group-hover:text-green-400',
|
|
},
|
|
warning: {
|
|
gradient: 'from-amber-500/10',
|
|
hoverBorder: 'hover:border-amber-500/40',
|
|
hoverText: 'group-hover:text-amber-400',
|
|
},
|
|
};
|
|
|
|
export const LinkCard = ({
|
|
href,
|
|
title,
|
|
description,
|
|
accent,
|
|
icon,
|
|
className = '',
|
|
}: LinkCardProps) => {
|
|
const styles = accentStyles[accent];
|
|
|
|
return (
|
|
<a
|
|
href={href}
|
|
className={`
|
|
block
|
|
p-5
|
|
bg-gradient-to-br ${styles.gradient} to-transparent
|
|
border border-slate-700/50
|
|
rounded-xl
|
|
${styles.hoverBorder}
|
|
transition-colors
|
|
group
|
|
${className}
|
|
`}
|
|
>
|
|
{icon && (
|
|
<div className="text-2xl mb-3">{icon}</div>
|
|
)}
|
|
<h3
|
|
className={`
|
|
text-lg font-semibold text-white mb-2
|
|
${styles.hoverText}
|
|
transition-colors
|
|
`}
|
|
>
|
|
{title}
|
|
</h3>
|
|
<p className="text-sm text-gray-400">
|
|
{description}
|
|
</p>
|
|
</a>
|
|
);
|
|
};
|