Rebuild devcontainer with pnpm-optimized Docker setup

.devcontainer/Dockerfile

@@ -0,0 +1,27 @@
+# Build stage for installing dependencies
+FROM node:22-bookworm
+
+# Install essential packages
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Enable corepack and pnpm
+RUN corepack enable && corepack prepare [email protected] --activate
+
+# Configure pnpm
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+
+# Set up workspace directory
+WORKDIR /workspace
+
+# Create node user with proper permissions if it doesn't exist
+RUN id -u node &>/dev/null || (groupadd --gid 1000 node && \
+    useradd --uid 1000 --gid node --shell /bin/bash --create-home node)
+
+# Ensure node user owns workspace
+RUN chown -R node:node /workspace
+
+# Switch to node user for all subsequent operations
+USER node

.devcontainer/README.md

@@ -1,6 +1,6 @@
 # Devcontainer Configuration
 
-This directory contains the configuration for GitHub Codespaces and VS Code Dev Containers.
+This directory contains the configuration for GitHub Codespaces and VS Code Dev Containers, optimized for pnpm monorepo development.
 
 ## Quick Start
 
@@ -18,21 +18,50 @@ With prebuilds enabled, your codespace will be ready in ~30 seconds instead of 5
 2. Open the repository in VS Code
 3. Press `F1` and select "Dev Containers: Reopen in Container"
 
+## Architecture
+
+### Custom Dockerfile
+
+Following [pnpm Docker best practices](https://pnpm.io/docker), we use a custom Dockerfile that:
+
+- Uses Node.js 22 (matching `.nvmrc` and `package.json` engines)
+- Enables pnpm 10.18.1 via corepack (matching `packageManager` in `package.json`)
+- Runs as the `node` user to avoid permission issues
+- Includes git and essential development tools
+
+### pnpm Store Caching
+
+The devcontainer uses a Docker volume (`ui-kit-pnpm-store`) to persist the pnpm store across container rebuilds. This significantly speeds up dependency installation:
+
+- First install: Downloads all dependencies
+- Subsequent installs: Reuses cached packages from the volume
+
+### Optimized Lifecycle
+
+The devcontainer uses GitHub Codespaces prebuild lifecycle:
+
+1. **`updateContentCommand`** - Runs during prebuild (slow operations)
+   - Installs all dependencies with frozen lockfile
+   - Builds all packages in the monorepo
+
+2. **`postStartCommand`** - Runs every time the codespace starts
+   - Displays a welcome message with quick start commands
+
+This separation ensures expensive operations are cached in the prebuild, while codespace startup remains fast.
+
 ## What's Included
 
 ### Pre-installed Tools
-- Node.js 22
-- pnpm (via corepack)
+- Node.js 22.17.1
+- pnpm 10.18.1
+- git
 - GitHub CLI
-- All dependencies installed (`pnpm install --frozen-lockfile`)
-- Full project build completed (`pnpm run build`)
 
 ### VS Code Extensions
 The following extensions are automatically installed:
 - Biome (formatter and linter)
 - Code Spell Checker
-- GitHub Copilot
-- GitHub Copilot Chat
+- GitHub Copilot & Copilot Chat
 - Lit Plugin
 - MDX Language Support
 - Playwright Test Runner
@@ -45,24 +74,6 @@ The following extensions are automatically installed:
 - Auto-organize imports: Enabled
 - LF line endings enforced
 
-## Lifecycle Commands
-
-The devcontainer uses an optimized lifecycle for GitHub Codespaces prebuilds:
-
-1. **`updateContentCommand`** - Runs during prebuild (slow operations)
-   - Enables pnpm via corepack
-   - Installs all dependencies with frozen lockfile
-   - Builds all packages
-
-2. **`postCreateCommand`** - Runs after prebuild (fast operations)
-   - Ensures pnpm is enabled
-
-3. **`postStartCommand`** - Runs every time the codespace starts
-   - Displays a welcome message
-
-This separation ensures that expensive operations (install & build) are cached in the prebuild,
-while codespace creation and startup remain fast.
-
 ## GitHub Codespaces Prebuilds
 
 Prebuilds must be configured in the repository settings:
@@ -75,49 +86,46 @@ Prebuilds must be configured in the repository settings:
    - **Trigger**: On push to main branch
 4. Click **Create**
 
-Once configured, prebuilds will be created automatically:
-- On every push to `main` branch
-- On schedule (configurable, recommended: daily or weekly)
-- When devcontainer configuration or dependencies change
-
 ### Benefits of Prebuilds
 - Reduces codespace creation from ~5 minutes to ~30 seconds
-- Pre-installs all dependencies (1.6GB of node_modules)
-- Pre-builds all 36 packages in the monorepo
+- Pre-installs all dependencies
+- Pre-builds all packages in the monorepo
 - Ensures consistent developer environment
 
-## Customization
+## Development Workflow
 
-To customize the devcontainer:
-1. Edit `devcontainer.json`
-2. Test locally with VS Code Dev Containers
-3. Commit and push to trigger a new prebuild
+Once your codespace is ready:
 
-## Benefits
+```bash
+# Start development with hot reload
+pnpm run dev:atomic
 
-### Before Optimization
-- Codespace creation: ~5 minutes
-- Manual dependency installation and build
-- No pre-configured VS Code extensions
-- Inconsistent developer environment
+# Run tests
+pnpm test
 
-### After Optimization
-- Codespace creation: ~30 seconds (with prebuild)
-- Dependencies and build pre-cached
-- All recommended extensions auto-installed
-- Consistent, production-ready environment
+# Run linting
+pnpm run lint:check
+
+# Build all packages
+pnpm run build
+```
 
 ## Troubleshooting
 
 ### Codespace takes a long time to start
 - Check if prebuilds are enabled in repository settings
 - Verify the prebuild workflow ran successfully
-- Consider manually triggering the prebuild workflow
+- Consider manually triggering a new prebuild
+
+### pnpm install fails
+- Ensure `pnpm-lock.yaml` is up to date
+- Try deleting the pnpm store volume: `docker volume rm ui-kit-pnpm-store`
+- Rebuild the container: "Dev Containers: Rebuild Container"
 
-### Build failures in prebuild
-- Check the prebuild logs in the Codespaces section of the repository settings
-- Ensure `pnpm install --frozen-lockfile` and `pnpm run build` work locally
-- Verify all dependencies are correctly specified in `pnpm-lock.yaml`
+### Permission errors
+- The container runs as the `node` user (UID 1000, GID 1000)
+- If you see permission errors, ensure your host files are accessible
+- On Linux, you may need to adjust file ownership
 
 ### Extensions not installing
 - Check VS Code output panel for extension installation logs
@@ -126,6 +134,7 @@ To customize the devcontainer:
 
 ## Resources
 
+- [pnpm Docker Guide](https://pnpm.io/docker)
 - [GitHub Codespaces Documentation](https://docs.github.com/en/codespaces)
 - [Dev Containers Specification](https://containers.dev/)
 - [Prebuild Configuration Guide](https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds)

.devcontainer/devcontainer.json

@@ -1,36 +1,28 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the
-// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
 {
-  "name": "Node.js & TypeScript",
-  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:2-22-bookworm",
+  "name": "UI Kit (pnpm)",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
 
-  // Features to add to the dev container. More info: https://containers.dev/features.
+  // Features to add to the dev container
   "features": {
     "ghcr.io/devcontainers/features/github-cli:1": {}
   },
 
-  // Use 'forwardPorts' to make a list of ports inside the container available locally.
-  // "forwardPorts": [],
-
-  // Lifecycle commands optimized for GitHub Codespaces prebuilds
-  // See: https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds
-
-  // postCreateCommand runs AFTER prebuild (fast for users)
-  // Used for quick setup tasks after a codespace is created
+  // Mount the pnpm store as a volume for better caching
+  "mounts": ["source=ui-kit-pnpm-store,target=/pnpm/store,type=volume"],
 
-  // updateContentCommand runs DURING prebuild (slow but cached)
-  // This is where expensive operations like install and build should go
-  "updateContentCommand": "bash -c 'CI=true corepack enable pnpm && pnpm install --frozen-lockfile && pnpm run build'",
+  // Lifecycle commands optimized for GitHub Codespaces
+  // updateContentCommand runs during prebuild (expensive operations cached)
+  "updateContentCommand": "pnpm install --frozen-lockfile && pnpm run build",
 
   // postStartCommand runs every time the codespace starts
-  // Keep this minimal for fast startup
-  "postStartCommand": "echo 'Codespace ready! Run pnpm run dev to start development.'",
+  "postStartCommand": "echo '✓ Codespace ready! Run pnpm run dev:atomic to start development.'",
 
-  // Configure tool-specific properties.
+  // Configure tool-specific properties
   "customizations": {
     "vscode": {
-      // Extensions that will be automatically installed
       "extensions": [
         "biomejs.biome",
         "streetsidesoftware.code-spell-checker",
@@ -42,7 +34,6 @@
         "bradlc.vscode-tailwindcss",
         "vitest.explorer"
       ],
-      // VS Code settings for better developer experience
       "settings": {
         "editor.defaultFormatter": "biomejs.biome",
         "editor.formatOnSave": true,
@@ -56,9 +47,6 @@
     }
   },
 
-  // User configuration - explicitly set to 'node' user to avoid permission issues
-  // The base image uses 'node' user by default, but explicit configuration
-  // helps VS Code properly initialize home directory and config files
   "remoteUser": "node",
   "containerUser": "node"
 }

.dockerignore

@@ -0,0 +1,55 @@
+# Git
+.git
+.gitignore
+.github
+
+# Dependencies
+node_modules
+
+# Build outputs
+dist
+reports
+sarifs
+
+# IDE
+.vscode
+.idea
+
+# Dev tools
+.devcontainer
+.husky
+
+# Logs
+npm-debug.log
+*.log
+
+# Cache
+.turbo
+.dccache
+.cspellcache
+.nx
+
+# Test files
+**/*.spec.*
+**/*.test.*
+**/*.cy.ts
+**.cy.ts.mp4
+
+# Storybook
+**/*.stories.tsx
+.storybook
+
+# Documentation
+internal-docs
+
+# Temporary files
+.size-snapshot.json
+topology.json
+topology-raw.json
+.git-message
+packages/atomic/custom-elements.json
+scripts/translation-gpt/temporary.json
+
+# Environment
+.env
+.env.local