Directory Structure
Relevant source files
The following files were used as context for generating this wiki page:
The @pcstyle/ui repository is structured as a modern TypeScript React library designed to provide a dual-theme design system. It utilizes a modular architecture where components, themes, and global state providers are decoupled but integrated through a central entry point. The project is configured as an ESM-first package, targeting modern browsers and build tools while maintaining strict type safety through TypeScript.
The repository follows a standard source-dist separation, where all development happens in the src directory, and compiled assets are output to dist for distribution. This structure supports multiple export entry points, including the main library, themes, and special effects.
Sources: package.json:1-25, tsconfig.json:1-15
Root Configuration
The root directory contains project-wide configuration files that define the build process, dependency management, and development standards.
| File | Purpose | Key Configurations |
|---|---|---|
package.json | Project metadata and dependencies | Defines exports for ., ./theme, and ./effects. Lists framer-motion and lucide-react as peer dependencies. |
tsconfig.json | TypeScript compiler settings | Targets ES2020, outputs to ./dist, and uses bundler module resolution. |
cubic.yaml | Repository governance | Defines strict typing rules and ESM standards for the SDK package. |
Sources: package.json:1-40, tsconfig.json:1-15, cubic.yaml:1-25
Source Directory (/src)
The /src directory is the core of the library, organized into functional subdirectories that separate UI components from styling logic and global providers.
Entry Point
The src/index.ts file serves as the primary aggregator for the library. It exports all public members from the theme system, the UI provider, components, and visual effects.
Sources: src/index.ts:1-15
Theme System (/src/theme)
This directory contains the design language of the project. It is split into colors and structural tokens.
colors.ts: Defines thecyber(aggressive neon) andminimal(clean modern) palettes.tokens.ts: Contains layout constants like typography (font family, size, weight), spacing, radii, and transition durations.index.ts: Re-exports all theme-related constants.
Sources: src/theme/colors.ts:5-40, src/theme/tokens.ts:5-65, src/theme/index.ts:1-2
Components (/src/components)
Components are categorized by their UI role. Each component is a functional React component using the "use client" directive for compatibility with React Server Components environments.
buttons/: Contains theButtoncomponent with variant support (primary, secondary, outline, ghost).layout/: Contains structural components likeCard.forms/: Contains input elements likeInput.feedback/: Contains status indicators likeBadge.overlays/: Contains navigation and layering components likeTabs.
Sources: src/components/buttons/Button.tsx:1-10, src/components/layout/Card.tsx:1-5, src/index.ts:4-10
State Provider (/src/provider)
The UIProvider (located in src/provider/index.tsx) manages the global theme state. It uses React Context to distribute the theme mode and synchronization logic to all child components.
Sources: src/provider/index.tsx:1-20
Effects (/src/effects)
This directory houses non-essential visual enhancements that reinforce the project's aesthetic, such as the CRTOverlay and NeuralCursor.
Sources: src/effects/crt-overlay.tsx:1-5, src/effects/neural-cursor.tsx:1-5
Component Architecture and Data Flow
The library uses a top-down data flow where components consume theme information from the UIProvider.
This diagram shows how the UIProvider acts as the central hub, distributing theme data derived from colors.ts to various components and effects.
Sources: src/provider/index.tsx:10-40, src/theme/colors.ts:5-10, src/components/buttons/Button.tsx:20-25
Build and Export Structure
The project is configured to produce a distributed build in the dist/ directory, mirroring the src/ structure for type definitions and modules.
The mapping between source files and package exports allows consumers to import only necessary modules, optimizing bundle sizes.
Sources: package.json:7-25, tsconfig.json:8-10
Summary of Directory Responsibilities
| Directory | Primary Responsibility | Key Files |
|---|---|---|
src/components | UI Atomic Units | Button.tsx, Input.tsx, Card.tsx |
src/theme | Visual Style Definitions | colors.ts, tokens.ts |
src/provider | Context & State | index.tsx (UIProvider) |
src/effects | Immersive Enhancements | crt-overlay.tsx, neural-cursor.tsx |
dist/ | Compiled Output | Generated .js and .d.ts files |
The directory structure of @pcstyle/ui is designed to support a scalable component library by separating static design tokens from dynamic React logic. By utilizing a central provider and modular component directories, the project ensures that theme changes (e.g., switching between "cyber" and "minimal") are propagated efficiently across the entire UI surface.
Sources: src/index.ts:1-15, src/provider/index.tsx:35-50, package.json:1-15