Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• src/index.ts
• src/theme/index.ts
• src/provider/index.tsx
• src/theme/colors.ts
• src/theme/tokens.ts
• src/components/buttons/Button.tsx
• package.json

The @pcstyle/ui project is a React-based design system and component library designed with a focus on dual-theme support, specifically catering to "Cyber" (aggressive/cyberpunk) and "Minimal" (clean/modern) aesthetics. The architecture leverages React Context for state management, Tailwind CSS for styling, and Framer Motion for animations to provide a cohesive and type-safe UI kit.

The system is structured as an ESM-first library, providing strict type safety and a clear separation between theme definitions, global state providers, and functional UI components. It is distributed via npm and intended for use in React 18+ environments.

Sources: package.json:2-10, src/provider/index.tsx:1-5

Core Systems

Theme Management and Provider

The central nervous system of the library is the UIProvider. This component manages the active ThemeMode ("cyber" or "minimal") and exposes a useUI hook for child components to consume the current state. The provider performs two primary functions:

1. React State Management: It holds the current theme in a useState hook and provides functions to set or toggle the theme.
2. CSS Variable Synchronization: It synchronizes theme-specific color values with CSS custom properties (e.g., --pc-primary) on the document root, allowing for global style consistency.

Design Tokens and Colors

The design system is built upon a structured set of tokens and color palettes. Colors are defined for each theme mode, while tokens define typography, spacing, and transition speeds that remain consistent or scale across the library.

Category	Key Tokens / Properties	Source
Colors (Cyber)	Primary (#ff00ff), Secondary (#00ffff), Glow, Surface	src/theme/colors.ts:7-19
Colors (Minimal)	Primary (#0a0a0a), Secondary (#666666), Border	src/theme/colors.ts:22-34
Typography	Font families (Mono, Sans), Sizes (xs to 4xl), Weights	src/theme/tokens.ts:6-38
Spacing	Scale from 0 to 16 (0rem to 4rem)	src/theme/tokens.ts:39-51
Transitions	Fast (150ms), Normal (300ms), Slow (500ms)	src/theme/tokens.ts:58-62

Sources: src/theme/colors.ts, src/theme/tokens.ts

Component Architecture

Components are built as functional React components that react dynamically to the theme context. They typically implement a "dual-style" logic where styles are branched based on the isCyber boolean derived from the useUI hook.

Component Structure Pattern

Most components follow a standard implementation pattern:

1. Access theme via useUI().
2. Define base styles (common to both themes).
3. Define theme-specific style objects or strings.
4. Render using a combination of these styles, often utilizing framer-motion for interaction effects.

Key Component Examples

Component	Features	Animations
Button	Variants (Primary, Secondary, Outline, Ghost), Sizes (sm, md, lg)	Framer Motion whileTap
Card	Variants (Default, Glass, Outline), Cyber-specific scanline gradient	Transition-all
Input	Mono font, Error states, Theme-aware focus rings	Transition-all
Tabs	Layout-shared animations for active indicators	Framer Motion layoutId

Sources: src/components/buttons/Button.tsx, src/components/layout/Card.tsx, src/components/overlays/Tabs.tsx

Visual Effects and Overlays

The library includes specialized environmental effects that enhance the "Cyber" theme. These are conditionally rendered based on the active theme.

• CRTOverlay: Adds scanlines and a vignette effect to the entire viewport when the cyber theme is active.
• NeuralCursor: A custom, trailing cursor effect that follows mouse movement with a slight delay and SVG connecting lines.

Sources: src/effects/crt-overlay.tsx:10-18, src/effects/neural-cursor.tsx:24-45

Module Exports and Distribution

The library uses a tiered export strategy defined in package.json and aggregated in src/index.ts. This allows consumers to import the entire library or specific sub-modules like themes or effects.

// Example from src/index.ts
export * from "./theme";
export * from "./provider";
export * from "./components/buttons/Button";
// ... other components
export * from "./effects/crt-overlay";

Sources: src/index.ts:1-15, package.json:11-23

Summary

The PCSTYLE UI architecture provides a robust framework for building themed React applications. By centralizing theme state in a React Context provider and utilizing a token-based styling approach, the library ensures that components remain consistent while offering dramatically different visual identities between the Cyber and Minimal modes. Sub-systems like specialized effects and strict TypeScript configurations further support a high-performance and developer-friendly experience.