design-system file-organization.instructions.md

File Organization Principles

Implementation Files (.ts/.tsx)

Organize implementation files in this order for better readability and maintainability:

// 1. Imports (external dependencies first, then internal)
import { externalLib } from 'external-package';
import { internalUtil } from '../utils';

// 2. Types and Interfaces (public API)
export interface PublicData {
  // Public types that consumers need
}

type InternalType = {
  // Internal types for implementation
};

// 3. Constants and Configuration
const CONFIG_VALUE = 'constant';
const REGEX_PATTERN = /pattern/;

// 4. Helper Functions (private implementation details)
const helperFunction = () => {
  // Internal utility functions
};

// 5. Main Exported Functions (primary public API)
export const mainFunction = () => {
  // Primary public functions
};

Key Principles:

• Public types first - What consumers need to import/use
• Constants grouped together - Configuration and static values
• Helper functions grouped together - Private implementation details
• Main exports last - Primary public API
• Separate concerns - Clear boundaries between public and private code

Test Files (.test.ts/.test.tsx)

Organize test files in this order for clarity and proper setup:

// 1. Imports
import { describe, it, expect, vi } from 'vitest';
import { functionToTest, type TypeToTest } from './moduleToTest';

// 2. Mocks (global setup that affects module loading)
vi.mock('external-dependency', () => ({
  // Mock implementation
}));

// 3. Constants and Test Data
const TEST_DATA = {
  // Static test data
};

const EXPECTED_VALUES = ['value1', 'value2'];

// 4. Helper Functions (test utilities)
const createTestInstance = () => {
  // Test setup helpers
};

const validateStructure = (item: TypeToTest) => {
  // Validation helpers
};

// 5. Test Suites (actual test execution)
describe('functionToTest', () => {
  // Test cases
});

Key Principles:

• Mocks immediately after imports - They're hoisted anyway and affect module loading
• Constants before helpers - Static configuration before dynamic utilities
• Helper functions before tests - Setup utilities before test execution
• Test suites last - Actual test execution comes after all setup