Baseline Components - MetaCogna Suite

This document provides standardized component specifications for the Paper UI design system. Use these as the baseline implementation for all MetaCogna Suite applications.

Overview

These baseline components follow Paper UI principles:

Digital Paper: Physical sheets with distinct borders and hard shadows
Hard Edges: Minimal border radius (max 2px)
High Contrast: Strict Ink/Paper polarity

PaperCard

The fundamental container component for content organization.

TypeScript Interface

interface PaperCardProps extends HTMLMotionProps<'div'> {
  title?: string;
  headerAction?: React.ReactNode;
  children: React.ReactNode;
  noPadding?: boolean;
  className?: string;
}

Implementation

export const PaperCard: React.FC<PaperCardProps> = ({ 
  title, 
  headerAction, 
  children, 
  className = '', 
  noPadding = false,
  ...props 
}) => {
  return (
    <motion.div 
      className={`bg-paper border-2 border-ink shadow-hard flex flex-col ${className}`}
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.4, ease: "easeOut" }}
      {...props}
    >
      {title && (
        <div className="border-b-2 border-ink bg-surface px-6 py-3 flex justify-between items-center">
          <h3 className="font-serif font-bold text-lg text-ink tracking-wide uppercase">
            {title}
          </h3>
          {headerAction && <div>{headerAction}</div>}
        </div>
      )}
      <div className={noPadding ? '' : 'p-6'}>
        {children}
      </div>
    </motion.div>
  );
};

Usage

<PaperCard title="Card Title">
  Card content goes here
</PaperCard>

<PaperCard title="Card with Action" headerAction={<button>Action</button>}>
  Content with header action
</PaperCard>

<PaperCard noPadding>
  Content without padding
</PaperCard>

Styling Specifications

Background: bg-paper (white/light background)
Border: border-2 border-ink (2px solid border)
Shadow: shadow-hard (4px 4px 0px 0px)
Title Typography: Serif font, bold, uppercase, tracking-wide
Padding: p-6 (default) or none if noPadding prop

Dark Mode

Automatically handled via CSS custom properties:

Paper becomes dark in dark mode
Ink becomes light in dark mode
Shadows adapt automatically

PaperButton

Interactive button component with variants and sizes.

TypeScript Interface

interface PaperButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  fullWidth?: boolean;
}

Implementation

export const PaperButton: React.FC<PaperButtonProps> = ({ 
  children, 
  variant = 'primary', 
  size = 'md', 
  fullWidth = false,
  className = '',
  ...props 
}) => {
  const baseStyles = "font-bold font-sans border-2 border-ink transition-all duration-100 active:translate-x-[2px] active:translate-y-[2px] active:shadow-none flex items-center justify-center gap-2 disabled:opacity-50 disabled:cursor-not-allowed";
  
  const variants = {
    primary: "bg-ink text-paper hover:bg-accent hover:text-ink hover:border-ink shadow-hard",
    secondary: "bg-paper text-ink hover:bg-surface shadow-hard",
    ghost: "bg-transparent border-transparent hover:border-ink hover:bg-surface text-ink shadow-none hover:shadow-hard",
    danger: "bg-paper text-warning border-2 border-warning shadow-hard hover:bg-warning hover:text-paper hover:border-ink",
  };

  const sizes = {
    sm: "text-xs px-3 py-1.5",
    md: "text-sm px-5 py-2.5",
    lg: "text-base px-8 py-4",
  };

  const widthClass = fullWidth ? 'w-full' : '';

  return (
    <button 
      className={`${baseStyles} ${variants[variant]} ${sizes[size]} ${widthClass} ${className}`}
      {...props}
    >
      {children}
    </button>
  );
};

Usage

<PaperButton variant="primary">Primary Button</PaperButton>
<PaperButton variant="secondary">Secondary Button</PaperButton>
<PaperButton variant="ghost">Ghost Button</PaperButton>
<PaperButton variant="danger">Danger Button</PaperButton>
<PaperButton size="sm">Small Button</PaperButton>
<PaperButton fullWidth>Full Width Button</PaperButton>

Variants

primary: Ink background, paper text, hover to accent
secondary: Paper background, ink text
ghost: Transparent, gains border and shadow on hover
danger: Warning color border and text

Active State

Buttons translate 2px in both X and Y directions on click (active:translate-x-[2px] active:translate-y-[2px]) to simulate physical button press.

PaperInput

Text input field with label and error support.

TypeScript Interface

interface PaperInputProps extends InputHTMLAttributes<HTMLInputElement> {
  label?: string;
  error?: string;
}

Implementation

export const PaperInput: React.FC<PaperInputProps> = ({ 
  label, 
  error, 
  className = '', 
  ...props 
}) => {
  return (
    <div className={`flex flex-col gap-1.5 ${className}`}>
      {label && (
        <label className="font-mono text-xs uppercase font-bold text-ink">
          {label}
        </label>
      )}
      <input 
        className="bg-paper border-2 border-ink p-3 text-ink font-mono text-sm placeholder-gray-400 focus:outline-none focus:ring-0 focus:shadow-hard transition-all duration-200"
        {...props}
      />
      {error && (
        <span className="text-red-600 dark:text-red-400 text-xs font-mono">
          {error}
        </span>
      )}
    </div>
  );
};

Usage

<PaperInput 
  label="USERNAME"
  placeholder="Enter username"
  value={username}
  onChange={(e) => setUsername(e.target.value)}
/>

<PaperInput 
  label="EMAIL"
  type="email"
  error="Invalid email address"
/>

Styling Specifications

Font: Monospace (font-mono) - Paper UI principle for technical inputs
Border: 2px solid ink border
Focus: Hard shadow (shadow-hard) instead of ring
Label: Monospace, uppercase, bold, tracking-wide
Error: Monospace font, warning color

PaperTextArea

Multi-line text input component.

TypeScript Interface

interface PaperTextAreaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
  label?: string;
  error?: string;
}

Implementation

export const PaperTextArea: React.FC<PaperTextAreaProps> = ({ 
  label, 
  error, 
  className = '', 
  ...props 
}) => {
  return (
    <div className={`flex flex-col gap-1.5 ${className}`}>
      {label && (
        <label className="font-mono text-xs uppercase font-bold text-ink">
          {label}
        </label>
      )}
      <textarea 
        className="bg-paper border-2 border-ink p-3 text-ink font-mono text-sm placeholder-gray-400 focus:outline-none focus:ring-0 focus:shadow-hard transition-all duration-200 min-h-[120px]"
        {...props}
      />
      {error && (
        <span className="text-red-600 dark:text-red-400 text-xs font-mono">
          {error}
        </span>
      )}
    </div>
  );
};

Usage

<PaperTextArea 
  label="DESCRIPTION"
  rows={5}
  value={description}
  onChange={(e) => setDescription(e.target.value)}
/>

PaperSelect

Dropdown select component with custom styling.

TypeScript Interface

interface PaperSelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
  label?: string;
  error?: string;
  options: { value: string; label: string }[];
}

Implementation

export const PaperSelect: React.FC<PaperSelectProps> = ({ 
  label, 
  error, 
  options, 
  className = '', 
  ...props 
}) => {
  return (
    <div className={`flex flex-col gap-1.5 ${className}`}>
      {label && (
        <label className="font-mono text-xs uppercase font-bold text-ink">
          {label}
        </label>
      )}
      <div className="relative">
        <select 
          className="appearance-none w-full bg-paper border-2 border-ink p-3 text-ink font-sans focus:outline-none focus:ring-0 focus:shadow-hard transition-all duration-200"
          {...props}
        >
          {options.map(opt => (
            <option key={opt.value} value={opt.value}>
              {opt.label}
            </option>
          ))}
        </select>
        <div className="pointer-events-none absolute inset-y-0 right-0 flex items-center px-2 text-ink">
          <svg className="fill-current h-4 w-4" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">
            <path d="M9.293 12.95l.707.707L15.657 8l-1.414-1.414L10 10.828 5.757 6.586 4.343 8z"/>
          </svg>
        </div>
      </div>
      {error && (
        <span className="text-red-600 dark:text-red-400 text-xs font-mono">
          {error}
        </span>
      )}
    </div>
  );
};

Usage

<PaperSelect
  label="LANGUAGE"
  options={[
    { value: 'en', label: 'English' },
    { value: 'es', label: 'Spanish' },
  ]}
  value={language}
  onChange={(e) => setLanguage(e.target.value)}
/>

PaperBadge

Status indicator and label component.

TypeScript Interface

interface PaperBadgeProps {
  children: React.ReactNode;
  color?: 'emerald' | 'blue' | 'purple' | 'orange' | 'red' | 'gray';
}

Implementation

export const PaperBadge: React.FC<PaperBadgeProps> = ({ 
  children, 
  color = 'gray' 
}) => {
  const colors = {
    emerald: "bg-emerald-50 dark:bg-emerald-900/50 text-emerald-800 dark:text-emerald-200 border-emerald-200 dark:border-emerald-700",
    blue: "bg-blue-50 dark:bg-blue-900/50 text-blue-800 dark:text-blue-200 border-blue-200 dark:border-blue-700",
    purple: "bg-purple-50 dark:bg-purple-900/50 text-purple-800 dark:text-purple-200 border-purple-200 dark:border-purple-700",
    orange: "bg-orange-50 dark:bg-orange-900/50 text-orange-800 dark:text-orange-200 border-orange-200 dark:border-orange-700",
    red: "bg-red-50 dark:bg-red-900/50 text-red-800 dark:text-red-200 border-red-200 dark:border-red-700",
    gray: "bg-gray-50 dark:bg-gray-800 text-gray-800 dark:text-gray-200 border-gray-200 dark:border-gray-600",
  };

  return (
    <span className={`inline-flex items-center px-2.5 py-0.5 border text-xs font-mono font-bold uppercase tracking-wider ${colors[color]}`}>
      {children}
    </span>
  );
};

Usage

<PaperBadge color="emerald">SUCCESS</PaperBadge>
<PaperBadge color="red">ERROR</PaperBadge>
<PaperBadge color="blue">INFO</PaperBadge>

Styling Specifications

Font: Monospace, uppercase, bold, tracking-wider
Size: text-xs (12px) for readability
Colors: Supports semantic colors with dark mode variants

PaperModal

Modal dialog component with overlay and animations.

TypeScript Interface

interface PaperModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
  maxWidth?: string;
}

Implementation

export const PaperModal: React.FC<PaperModalProps> = ({ 
  isOpen, 
  onClose, 
  title, 
  children, 
  maxWidth = "max-w-lg" 
}) => {
  return (
    <AnimatePresence>
      {isOpen && (
        <div className="fixed inset-0 z-[100] flex items-center justify-center p-4">
          <motion.div 
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            className="absolute inset-0 bg-ink/30 backdrop-blur-sm"
            onClick={onClose}
          />
          <motion.div
            initial={{ opacity: 0, scale: 0.95, y: 10 }}
            animate={{ opacity: 1, scale: 1, y: 0 }}
            exit={{ opacity: 0, scale: 0.95, y: 10 }}
            className={`relative z-10 w-full ${maxWidth} max-h-[95vh] overflow-y-auto`}
          >
            <PaperCard 
              title={title} 
              headerAction={
                <button onClick={onClose} className="hover:text-accent transition-colors text-ink">
                  <X className="w-5 h-5" />
                </button>
              }
            >
              {children}
            </PaperCard>
          </motion.div>
        </div>
      )}
    </AnimatePresence>
  );
};

Usage

<PaperModal 
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  title="Modal Title"
>
  Modal content goes here
</PaperModal>

Animation Guidelines

Card Animations

Cards should use subtle fade-in animations:

initial={{ opacity: 0, y: 20 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.4, ease: "easeOut" }}

Button Interactions

Buttons should translate on active state:

active:translate-x-[2px] active:translate-y-[2px] active:shadow-none

Modals should scale and fade:

initial={{ opacity: 0, scale: 0.95, y: 10 }}
animate={{ opacity: 1, scale: 1, y: 0 }}
exit={{ opacity: 0, scale: 0.95, y: 10 }}

Dark Mode Support

All components automatically support dark mode through CSS custom properties:

Colors: Defined in :root and .dark selectors
Components: Use semantic tokens (bg-paper, text-ink, etc.)
No changes needed: Components adapt automatically

Ensure your Tailwind configuration uses CSS custom properties for colors. See Tailwind Configuration for details.

Dependencies

Required dependencies:

{
  "dependencies": {
    "react": "^18.0.0",
    "framer-motion": "^10.0.0"
  },
  "devDependencies": {
    "tailwindcss": "^3.0.0",
    "@types/react": "^18.0.0"
  }
}

Design System - Paper UI design principles
Tailwind Configuration - Setup guide
Component Guide - Usage patterns
Application Review - Implementation review

​Overview

​PaperCard

​TypeScript Interface

​Implementation

​Usage

​Styling Specifications

​Dark Mode

​PaperButton

​TypeScript Interface

​Implementation

​Usage

​Variants

​Active State

​PaperInput

​TypeScript Interface

​Implementation

​Usage

​Styling Specifications

​PaperTextArea

​TypeScript Interface

​Implementation

​Usage

​PaperSelect

​TypeScript Interface

​Implementation

​Usage

​PaperBadge

​TypeScript Interface

​Implementation

​Usage

​Styling Specifications

​PaperModal

​TypeScript Interface

​Implementation

​Usage

​Animation Guidelines

​Card Animations

​Button Interactions

​Modal Animations

​Dark Mode Support

​Dependencies

​Related Documentation

Overview

PaperCard

TypeScript Interface

Implementation

Usage

Styling Specifications

Dark Mode

PaperButton

TypeScript Interface

Implementation

Usage

Variants

Active State

PaperInput

TypeScript Interface

Implementation

Usage

Styling Specifications

PaperTextArea

TypeScript Interface

Implementation

Usage

PaperSelect

TypeScript Interface

Implementation

Usage

PaperBadge

TypeScript Interface

Implementation

Usage

Styling Specifications

PaperModal

TypeScript Interface

Implementation

Usage

Animation Guidelines

Card Animations

Button Interactions

Modal Animations

Dark Mode Support

Dependencies

Related Documentation