Project Structure

colorx/
  packages/
    core/                # Standalone TS library (@colorx/core)
      src/
        types.ts         # ThemeColors, ContrastResult, ThemeOutput, APCAResult, CVDType
        color-math.ts    # Color conversion: hex, RGB, HSL
        contrast.ts      # WCAG 2.1 contrast ratio + enforcement
        apca.ts          # APCA Lc contrast algorithm (WCAG 3.0 draft)
        cvd.ts           # Color vision deficiency simulation (Brettel/Vienot matrices)
        theme.ts         # Light/dark theme generation + audit
        css.ts           # CSS custom properties output
        index.ts         # Barrel export
      tests/             # 42 tests across 5 suites
  apps/
    web/                 # React SPA (@colorx/web)
      src/
        components/
          ui/            # shadcn/ui (Button, Card, Badge, Tabs, Table, Separator, Tooltip)
          layout/        # RootLayout, Nav, Footer, SkipLink
            primitives/  # Container, Stack, Grid, Flex
          color-input/   # ColorPicker, ColorForm
          theme-display/ # ThemeTabs, SwatchGrid, Swatch, UIPreview
          contrast/      # ContrastAudit, ContrastBadge, APCABadge
          cvd/           # CVDSimulation, CVDPreview
          output/        # CSSOutput, CopyButton
          landing/       # Hero, DemoPreview, HowItWorks, Features, WCAGExplainer, TokenReference, CTABottom
          common/        # AnimateIn, ErrorBoundary, LowCarbonImage, VisuallyHidden
        hooks/
          useDocumentTitle.ts   # Per-page document title
          usePreferences.ts     # Dark/a11y/low-carbon state (useSyncExternalStore)
          useTheme.ts           # ThemeContext consumer
          useAPCA.ts            # APCA audit for theme pairs
          useCVD.ts             # CVD simulation for themes
          useCopyToClipboard.ts # Clipboard API + SR announcement
          useReducedMotion.ts   # prefers-reduced-motion
          useAnnounce.ts        # aria-live announcements
        context/
          ThemeContext.tsx       # Hex input + generated ThemeOutput
          AnnounceContext.tsx    # Screen reader announcement provider
        pages/
          LandingPage.tsx
          GeneratorPage.tsx
          NotFoundPage.tsx

Monorepo

• pnpm workspaces with packages/* and apps/*
• @colorx/core referenced via workspace:* protocol
• Vite resolves @colorx/core to source during dev (no build step needed)
• @/ alias maps to apps/web/src/ for clean imports

Layout Primitives

Custom polymorphic components in layout/primitives/:

Component	Purpose	Props
Container	Centered max-width wrapper	as, size (sm/md/lg/xl)
Stack	Vertical flex layout	as, gap
Grid	Responsive CSS grid	as, cols (1-4), gap
Flex	Horizontal flex layout	as, gap, align, justify, wrap, direction

All support polymorphic as prop for semantic HTML (section, nav, ul, ol, li, article, header, footer).