Component Organization Patterns

Guidelines for structuring React components in the Shadow Master codebase.

Component Directory Overview

/components/                    # 130+ components total
├── index.ts                    # Root exports (DiceRoller only)
├── *.tsx                       # 6 standalone utility components
├── action-resolution/          # 3 components - dice pool building
├── auth/                       # 1 component - email verification
├── character/                  # 12 components - character sheet display
├── combat/                     # 4 components - combat tracking UI
├── creation/                   # 83 components - character creation
│   ├── *.tsx                   # 14 top-level cards
│   ├── shared/                 # 14 reusable utilities
│   └── {feature}/              # 17 feature subfolders
├── cyberlimbs/                 # 6 components - augmentation UI
├── sync/                       # 2 components - ruleset sync status
└── ui/                         # 2 components - BaseModal, Tooltip

Decision Flowchart

Does the component have modals?
├─ Yes → Create subfolder, extract modals
└─ No → Does it have reusable Row/ListItem components?
        ├─ Yes, used elsewhere → Create subfolder
        └─ No → Keep as single file with internal helpers

When to Use a Subfolder

Create a subfolder with

index.ts

• Component has one or more modals (selection dialogs, forms, etc.)
• Component has reusable row/list item components used in multiple places
• Component exceeds ~600 lines with clear separable concerns
• Component has distinct UI pieces that could be tested independently

Subfolder structure:

/components/{area}/{feature}/
├── FeatureCard.tsx           # Main component
├── FeatureModal.tsx          # Selection/edit modal
├── FeatureRow.tsx            # Optional: if row is complex/reusable
├── constants.ts              # Optional: magic values, options arrays
├── types.ts                  # Optional: feature-specific types
├── utils.ts                  # Optional: feature-specific helpers
├── index.ts                  # Re-exports public API

Index file pattern:

// index.ts - export only public API
export { FeatureCard } from "./FeatureCard";
export { FeatureModal } from "./FeatureModal"; // Only if used externally

When to Keep as Single File

Keep as a single file when:

• Component is self-contained with only internal helper components
• Internal components are tightly coupled and only make sense within the parent
• Component is under ~400 lines with straightforward structure
• No modals or independently reusable pieces

Component Areas

Root-Level Components (6 files)

Standalone utility components that don't fit a specific feature area:

DiceRoller.tsx

AugmentationCard.tsx

EssenceDisplay.tsx

ThemeProvider.tsx

EnvironmentBadge.tsx

NotificationBell.tsx

/components/ui/

- Shared UI Primitives

Low-level accessible components used across the app. Built on React Aria.

BaseModal.tsx

Tooltip.tsx

When to add here: Generic UI primitives with no business logic.

/components/auth/

- Authentication Components

EmailVerificationBanner.tsx

/components/action-resolution/

- Dice Pool Building

Components for building and displaying action resolution dice pools.

ActionHistory.tsx

ActionPoolBuilder.tsx

EdgeTracker.tsx

Note: No index.ts - import directly from files.

/components/character/

- Character Sheet Display

Components for viewing active characters (not creation). No index file - import directly.

AdeptPowerList.tsx

AutosoftManager.tsx

CyberdeckConfig.tsx

DroneNetworkManager.tsx

JumpInControl.tsx

MagicSummary.tsx

MatrixActions.tsx

MatrixSummary.tsx

ProgramManager.tsx

RiggingSummary.tsx

Spellbook.tsx

VehicleActions.tsx

/components/combat/

- Combat Tracking

Components for running combat encounters. Has index.ts and co-located tests.

CombatTracker.tsx

ActionSelector.tsx

ConditionMonitor.tsx

OpposedTestResolver.tsx

/components/cyberlimbs/

- Cyberlimb Management

Components for cyberlimb augmentation display and modification.

CyberlimbCard.tsx

CyberlimbList.tsx

CyberlimbDetailPanel.tsx

CyberlimbInstallModal.tsx

CyberlimbEnhancementModal.tsx

CyberlimbAccessoryModal.tsx

/components/sync/

- Ruleset Synchronization

Components for displaying ruleset sync status and migration.

StabilityShield.tsx

MigrationWizard.tsx

/components/creation/

- Character Creation

The largest component area (83 components). Organized by feature with shared utilities.

Top-Level Cards (14 files)

Single-file cards without complex modals:

PrioritySelectionCard

AttributesCard

SkillsCard

SpellsCard

AdeptPowersCard

ComplexFormsCard

AugmentationsCard

VehiclesCard

WeaponsPanel

GearTabsCard

DerivedStatsCard

CharacterInfoCard

EditionSelector

CreationErrorBoundary

Feature Subfolders (17 directories)

/armor

/augmentations

/contacts

/foci

/gear

/identities

/knowledge-languages

/magic-path

/matrix-gear

/metatype

/qualities

/shared

/skills

/spells

/vehicles

/weapons

Shared Utilities (

/creation/shared/

)

CreationCard.tsx

BudgetIndicator.tsx

CardSkeleton.tsx

EmptyState.tsx

KarmaConversionModal.tsx

RatingSelector.tsx

Stepper.tsx

SummaryFooter.tsx

ValidationBadge.tsx

BulkQuantitySelector.tsx

LifestyleModificationSelector

LifestyleSubscriptionSelector

useKarmaConversionPrompt.ts

Adding Components by Area

Adding a Creation Card

1. Determine structure using the decision flowchart
2. Create in

   /components/creation/

   or

   /components/creation/{feature}/

3. Use

   CreationCard

   wrapper from

   /components/creation/shared/

4. Add to

   SheetCreationLayout.tsx

   in appropriate column
5. Update

   CreationState

   type in

   /lib/types/creation.ts

   if needed
6. Export from

   /components/creation/index.ts

Adding a Combat Component

1. Create in

   /components/combat/

2. Export from

   /components/combat/index.ts

3. Add co-located test in

   /components/combat/__tests__/

Adding a Character Sheet Component

1. Create in

   /components/character/

2. Import directly from file (no index.ts)
3. Add to relevant page in

   /app/characters/[id]/

Adding a Cyberlimb Component

1. Create in

   /components/cyberlimbs/

2. Export from

   /components/cyberlimbs/index.ts

3. Export types if needed for external use

Adding a UI Primitive

1. Create in

   /components/ui/

2. Build on React Aria for accessibility
3. Export from

   /components/ui/index.ts

4. No business logic - pure presentation

Adding a New API Endpoint

1. Create

   /app/api/{path}/route.ts

2. Export HTTP method handlers (GET, POST, PUT, DELETE)
3. Follow authentication pattern (getSession → validate user)
4. Call storage layer functions
5. Return JSON responses

Adding a New Ruleset Module

1. Define module type in

   /lib/types/edition.ts

2. Add module to book payload in

   /data/editions/{editionCode}/

3. Update merge logic in

   /lib/rules/merge.ts

   if special handling needed
4. Create hook in

   RulesetContext.tsx

   for easy access

Key Reference Files

• components/ui/BaseModal.tsx

  - Accessible modal foundation

• components/creation/shared/CreationCard.tsx

  - Card wrapper pattern

• components/creation/SkillsCard.tsx

  - Modal-based editing example

• components/combat/CombatTracker.tsx

  - Combat component with tests

• components/cyberlimbs/index.ts

  - Feature folder export pattern

• app/characters/create/sheet/components/SheetCreationLayout.tsx

  - Three-column layout

Component Diagram Generation

Mermaid diagrams are auto-generated from the component structure.

Commands

# Preview all areas to stdout
pnpm generate-diagrams

# Generate specific area
pnpm generate-diagrams --area=combat
pnpm generate-diagrams --area=creation

# Update documentation files
pnpm generate-diagrams --output=files

# Verbose mode with component counts
pnpm generate-diagrams --verbose

Output Locations

--output=stdout

--output=files

/docs/architecture/components/

Diagram Color Key

#3b82f6

*Card.tsx

*Panel.tsx

*Tracker.tsx

#8b5cf6

*Modal.tsx

#22c55e

*Row.tsx

*ListItem.tsx

#f59e0b

use*.ts

*Context.tsx

#6b7280

When to Regenerate

Run

pnpm generate-diagrams --output=files

• Adding a new component folder
• Adding/removing modals or cards
• Reorganizing component structure
• Before major documentation updates

Validation

# Validate creation docs structure (doesn't regenerate)
pnpm validate-creation-docs --verbose

Documentation Structure

Hand-Written (detailed)

/docs/architecture/creation-components/

• Component descriptions
• Props documentation
• Usage patterns
• Context dependencies

Auto-Generated (overview)

/docs/architecture/components/

• Mermaid component trees
• Summary tables
• Color-coded by type

Index File Conventions

/ui

/combat

/cyberlimbs

/sync

/creation

/character

/action-resolution

/auth