# Codex: Project Overview and Codebase Structure

## Project Overview
- Package: `@design.estate/dees-catalog`
- Focus: Web Components library providing UI elements and layouts for modern web apps.

## Directory Layout
- ts_web/: TypeScript source files
  - elements/: Individual Web Component definitions
  - pages/: Page-level templates for composite layouts
- html/: Demo/app entry point loading the bundled scripts
- dist_bundle/: Bundled browser JS and source maps
- dist_ts_web/: ES module outputs for TypeScript/web consumers
- dist_watch/: Watch-mode development bundle with live reload
- test/: Browser-based tests using `@push.rocks/tapbundle`

## Component Patterns
- Each component in ts_web/elements/:
  - Decorated with `@customElement('tag-name')`
  - Extends `DeesElement` from `@design.estate/dees-element`
  - Uses `@property` for reactive, reflected attributes
  - Defines `static styles = [cssManager.defaultStyles, css`...`]`
  - Implements `render()` returning a Lit `html` template with slots or markup
  - Exposes a demo via `public static demo` linking to `.demo.ts` files

## Build & Development Workflow
- Install dependencies: `npm install` or `pnpm install`
- Build production bundle: `npm run build`
- Start dev watch mode: `npm run watch`
- Run tests: `npm test` (launches browser fixtures)

## Theming & Utilities
- Default global styles via `cssManager.defaultStyles`
- Theme-aware values with `cssManager.bdTheme(light, dark)`
- DOM utilities set up in `html/index.ts` using `@design.estate/dees-domtools`

## Documentation
- `readme.md` provides an overview of all components and basic usage
- Live examples in `.demo.ts` files
  accessible via component `demo` static property

## Updates to this file
If you have pattern insisights or general changes to the codebase, please update this file.