@design.estate/dees-catalog 9.6.0 → 9.6.2

package/readme.playbook.md

@@ -1,820 +0,0 @@
-# UI Components Playbook
-
-This playbook provides comprehensive guidance for creating and maintaining UI components in the @design.estate/dees-catalog library. Follow these patterns and best practices to ensure consistency, maintainability, and quality.
-
-## Table of Contents
-
-1. [Component Creation Checklist](#component-creation-checklist)
-2. [Architectural Patterns](#architectural-patterns)
-3. [Component Types and Base Classes](#component-types-and-base-classes)
-4. [Theming System](#theming-system)
-5. [Event Handling](#event-handling)
-6. [State Management](#state-management)
-7. [Form Components](#form-components)
-8. [Overlay Components](#overlay-components)
-9. [Complex Components](#complex-components)
-10. [Performance Optimization](#performance-optimization)
-11. [Focus Management](#focus-management)
-12. [Demo System](#demo-system)
-13. [Common Pitfalls and Anti-patterns](#common-pitfalls-and-anti-patterns)
-14. [Code Examples](#code-examples)
-
-## Component Creation Checklist
-
-When creating a new component, follow this checklist:
-
-- [ ] Choose the appropriate base class (`DeesElement` or `DeesInputBase`)
-- [ ] Use `@customElement('dees-componentname')` decorator
-- [ ] Import `themeDefaultStyles` from `00theme.js` and style with `--dees-*` tokens (`cssManager.bdTheme()` is legacy — see [Theming System](#theming-system))
-- [ ] Create demo function in separate `.demo.ts` file
-- [ ] Export component from `ts_web/elements/index.ts`
-- [ ] Use proper TypeScript types and interfaces (prefix with `I` for interfaces, `T` for types)
-- [ ] Implement proper event handling with bubbling and composition
-- [ ] Consider mobile responsiveness
-- [ ] Add focus states for accessibility
-- [ ] Clean up resources in `destroy()` method
-- [ ] Follow lowercase naming convention for files
-- [ ] Add z-index registry support if it's an overlay component
-
-## Architectural Patterns
-
-### Base Component Structure
-
-```typescript
-import { customElement, property, state, css, TemplateResult, html, cssManager } from '@design.estate/dees-element';
-import { DeesElement } from '@design.estate/dees-element';
-import { themeDefaultStyles } from '../00theme.js';
-import * as demoFunc from './dees-componentname.demo.js';
-
-@customElement('dees-componentname')
-export class DeesComponentName extends DeesElement {
-  // Static demo reference
-  public static demo = demoFunc.demoFunc;
-
-  // Public properties (reactive, can be set via attributes)
-  @property({ type: String })
-  public label: string = '';
-
-  @property({ type: Boolean, reflect: true })
-  public disabled: boolean = false;
-
-  // Internal state (reactive, but not exposed as attributes)
-  @state()
-  private internalState: string = '';
-
-  // Static styles with theme support
-  public static styles = [
-    themeDefaultStyles,
-    cssManager.defaultStyles,
-    css`
-      :host {
-        display: block;
-        background: var(--dees-color-bg-primary);
-      }
-    `
-  ];
-
-  // Render method
-  public render(): TemplateResult {
-    return html`
-      <div class="main-container">
-        <!-- Component content -->
-      </div>
-    `;
-  }
-
-  // Lifecycle methods
-  public connectedCallback() {
-    super.connectedCallback();
-    // Setup that needs DOM access
-  }
-
-  public async firstUpdated() {
-    // One-time initialization after first render
-  }
-
-  // Cleanup
-  public destroy() {
-    // Clean up listeners, observers, registrations
-    super.destroy();
-  }
-}
-```
-
-### Advanced Patterns
-
-#### 1. Separation of Concerns (Complex Components)
-
-For complex components like WYSIWYG editors, separate concerns into handler classes:
-
-```typescript
-export class DeesComplexComponent extends DeesElement {
-  // Orchestrator pattern - main component coordinates handlers
-  private inputHandler: InputHandler;
-  private stateHandler: StateHandler;
-  private renderHandler: RenderHandler;
-
-  constructor() {
-    super();
-    this.inputHandler = new InputHandler(this);
-    this.stateHandler = new StateHandler(this);
-    this.renderHandler = new RenderHandler(this);
-  }
-}
-```
-
-#### 2. Singleton Pattern (Global Components)
-
-For global UI elements like menus:
-
-```typescript
-export class DeesGlobalMenu extends DeesElement {
-  private static instance: DeesGlobalMenu;
-
-  public static getInstance(): DeesGlobalMenu {
-    if (!DeesGlobalMenu.instance) {
-      DeesGlobalMenu.instance = new DeesGlobalMenu();
-      document.body.appendChild(DeesGlobalMenu.instance);
-    }
-    return DeesGlobalMenu.instance;
-  }
-}
-```
-
-#### 3. Registry Pattern (Z-Index Management)
-
-Use centralized registries for global state:
-
-```typescript
-class ComponentRegistry {
-  private static instance: ComponentRegistry;
-  private registry = new WeakMap<HTMLElement, number>();
-  
-  public register(element: HTMLElement, value: number) {
-    this.registry.set(element, value);
-  }
-  
-  public unregister(element: HTMLElement) {
-    this.registry.delete(element);
-  }
-}
-```
-
-## Component Types and Base Classes
-
-### Standard Component (extends DeesElement)
-
-Use for most UI components:
-- Buttons, badges, icons
-- Layout components
-- Data display components
-- Overlay components
-
-### Form Input Component (extends DeesInputBase)
-
-Use for all form inputs:
-- Text inputs, dropdowns, checkboxes
-- Date pickers, file uploads
-- Rich text editors
-
-**Required implementations:**
-```typescript
-export class DeesInputCustom extends DeesInputBase<ValueType> {
-  // Required: Get current value
-  public getValue(): ValueType {
-    return this.value;
-  }
-
-  // Required: Set value programmatically
-  public setValue(value: ValueType): void {
-    this.value = value;
-    this.changeSubject.next(this); // Notify form
-  }
-
-  // Optional: Custom validation
-  public async validate(): Promise<boolean> {
-    // Custom validation logic
-    return true;
-  }
-}
-```
-
-## Theming System
-
-### DO: Use Design Tokens
-
-The canonical theming system is the `--dees-*` token vocabulary defined in `ts_web/elements/00theme.ts`. Import `themeDefaultStyles` as the **first** entry of every component's static styles and style exclusively through tokens:
-
-```typescript
-import { themeDefaultStyles } from '../00theme.js';
-
-public static styles = [
-  themeDefaultStyles,
-  cssManager.defaultStyles,
-  css`
-    :host {
-      background: var(--dees-color-bg-primary);
-      color: var(--dees-color-text-primary);
-      border: 1px solid var(--dees-color-border-default);
-      border-radius: var(--dees-radius-md);
-      padding: var(--dees-spacing-md) var(--dees-spacing-lg);
-      transition: background var(--dees-transition-default);
-    }
-    :host(:hover) {
-      background: var(--dees-color-hover);
-    }
-  `
-];
-
-// ❌ INCORRECT
-background: #ffffff;                                  // hard-coded color
-background: ${cssManager.bdTheme('#fff', '#09090b')}; // legacy per-call theming
-```
-
-Token families: `--dees-color-bg-*`, `--dees-color-text-*` (incl. `-success`/`-warning`/`-error`), `--dees-color-border-*`, `--dees-color-accent-*`, `--dees-color-badge-*`, interactive states (`--dees-color-hover/active/pressed/row-hover`), `--dees-color-focus-ring`, tooltip/link/code/selection/scrollbar colors, plus `--dees-spacing-*`, `--dees-radius-*`, `--dees-shadow-*`, `--dees-transition-*`, and `--dees-control-height-*`. Check `00theme.ts` for the full list before inventing a value.
-
-### DO: Derive Tints with color-mix
-
-For alpha tints of a semantic color (hover washes, selection tints), derive from the token instead of hard-coding another color pair:
-
-```typescript
-background: color-mix(in srgb, var(--dees-color-accent-primary) 10%, transparent);
-```
-
-### Legacy: cssManager.bdTheme()
-
-`cssManager.bdTheme(lightValue, darkValue)` is the legacy per-call theming mechanism. It remains functional (the token layer in `00theme.ts` is itself implemented through it — that file is the single sanctioned usage), but **no new `bdTheme()` call sites are allowed** outside `00theme.ts`. A ratchet check (`node scripts/check-bdtheme-ratchet.cjs`, part of `pnpm test`) enforces this: per-file counts may only shrink. See `readme.theme-migration.md` for the bdTheme → token mapping used during migration.
-
-## Event Handling
-
-### DO: Dispatch Custom Events Properly
-
-```typescript
-// ✅ CORRECT - Events bubble and cross shadow DOM
-this.dispatchEvent(new CustomEvent('dees-componentname-change', {
-  detail: { value: this.value },
-  bubbles: true,
-  composed: true
-}));
-
-// ❌ INCORRECT - Event won't propagate properly
-this.dispatchEvent(new CustomEvent('change', {
-  detail: { value: this.value }
-  // Missing bubbles and composed
-}));
-```
-
-### DO: Use Event Delegation
-
-For dynamic content, use event delegation:
-
-```typescript
-// ✅ CORRECT - Single listener for all items
-this.addEventListener('click', (e: MouseEvent) => {
-  const item = (e.target as HTMLElement).closest('.item');
-  if (item) {
-    this.handleItemClick(item);
-  }
-});
-
-// ❌ INCORRECT - Multiple listeners
-this.items.forEach(item => {
-  item.addEventListener('click', () => this.handleItemClick(item));
-});
-```
-
-## State Management
-
-### DO: Use Appropriate Property Decorators
-
-```typescript
-// Public API - use @property
-@property({ type: String })
-public label: string;
-
-// Internal state - use @state
-@state()
-private isLoading: boolean = false;
-
-// Reflect to attribute when needed
-@property({ type: Boolean, reflect: true })
-public disabled: boolean = false;
-```
-
-### DON'T: Manipulate State in Render
-
-```typescript
-// ❌ INCORRECT - Side effects in render
-public render() {
-  this.counter++; // Don't modify state
-  return html`<div>${this.counter}</div>`;
-}
-
-// ✅ CORRECT - Pure render function
-public render() {
-  return html`<div>${this.counter}</div>`;
-}
-```
-
-## Form Components
-
-### DO: Extend DeesInputBase
-
-All form inputs must extend the base class:
-
-```typescript
-export class DeesInputNew extends DeesInputBase<string> {
-  // Inherits: key, label, value, required, disabled, validationState
-}
-```
-
-### DO: Emit Changes Consistently
-
-```typescript
-private handleInput(e: Event) {
-  this.value = (e.target as HTMLInputElement).value;
-  this.changeSubject.next(this); // Notify form system
-}
-```
-
-### DO: Support Standard Form Properties
-
-```typescript
-// All form inputs should support:
-@property() public key: string;
-@property() public label: string;
-@property() public required: boolean = false;
-@property() public disabled: boolean = false;
-@property() public validationState: 'valid' | 'warn' | 'invalid';
-```
-
-## Overlay Components
-
-### DO: Use Z-Index Registry
-
-Never hardcode z-index values:
-
-```typescript
-// ✅ CORRECT
-import { zIndexRegistry } from './00zindex.js';
-
-public async show() {
-  this.modalZIndex = zIndexRegistry.getNextZIndex();
-  zIndexRegistry.register(this, this.modalZIndex);
-  this.style.zIndex = `${this.modalZIndex}`;
-}
-
-public async hide() {
-  zIndexRegistry.unregister(this);
-}
-
-// ❌ INCORRECT
-public async show() {
-  this.style.zIndex = '9999'; // Hardcoded z-index
-}
-```
-
-### DO: Use Window Layers
-
-For modal backdrops:
-
-```typescript
-import { DeesWindowLayer } from './dees-windowlayer.js';
-
-private windowLayer: DeesWindowLayer;
-
-public async show() {
-  this.windowLayer = new DeesWindowLayer();
-  this.windowLayer.zIndex = zIndexRegistry.getNextZIndex();
-  document.body.append(this.windowLayer);
-}
-```
-
-## Complex Components
-
-### DO: Use Handler Classes
-
-For complex logic, separate into specialized handlers:
-
-```typescript
-// wysiwyg/handlers/input.handler.ts
-export class InputHandler {
-  constructor(private component: DeesInputWysiwyg) {}
-  
-  public handleInput(event: InputEvent) {
-    // Specialized input handling
-  }
-}
-
-// Main component orchestrates
-export class DeesInputWysiwyg extends DeesInputBase {
-  private inputHandler = new InputHandler(this);
-}
-```
-
-### DO: Use Programmatic Rendering
-
-For performance-critical updates that shouldn't trigger re-renders:
-
-```typescript
-// ✅ CORRECT - Direct DOM manipulation when needed
-private updateBlockContent(blockId: string, content: string) {
-  const blockElement = this.shadowRoot.querySelector(`#${blockId}`);
-  if (blockElement) {
-    blockElement.textContent = content; // Direct update
-  }
-}
-
-// ❌ INCORRECT - Triggering full re-render
-private updateBlockContent(blockId: string, content: string) {
-  this.blocks.find(b => b.id === blockId).content = content;
-  this.requestUpdate(); // Unnecessary re-render
-}
-```
-
-## Streaming Components (harness pattern)
-
-Components that render continuously arriving data (agent chat, logs) follow the harness pattern from `00group-harness`:
-
-- **Props are the source of truth; deltas are the fast path.** The host owns the array (e.g. `.messages`). Incremental updates go through `applyDelta()`, which mutates the same object instance held in the array and normally calls `requestUpdate()` on the one affected child element. Top-level tool updates also refresh derived activity. A later wholesale re-assignment of the array is therefore idempotent — no divergence between streamed and re-set state.
-- **Keyed `repeat` for identity.** List children render via `directives.repeat` keyed by a stable id so streaming never recreates sibling DOM (which would drop scroll position, expansion state, and selection).
-- **Cheap while streaming, rich when done.** `markdownWhileStreaming` defaults to `true`, so active markdown is parsed on a throttled ≥150 ms, token-guarded path while syntax highlighting waits for the final parse. Set the policy to `false` on a chat, message list, message, or tool card to keep active text plain and perform one final parse at `message-end`; the assembled chat forwards the setting through outer messages and nested subtask transcripts.
-- **Scroll follow with user override.** Auto-scroll only when the user is already pinned to the bottom (`scrollHeight - scrollTop - clientHeight < threshold`); otherwise show a "jump to latest" chip. Intent-based following remains active until explicit user scroll intent, while deferred frame checks and the `ResizeObserver` re-pin only when the scroll content grows. Streamed growth and the scroll therefore move as one motion without treating disclosure shrink as new content. Disconnect the observer and clear its size baseline in `disconnectedCallback`; retained hidden nested transcripts disable auto-follow observation until reopened.
-- **Interaction state lives on the child.** Expand/collapse (reasoning, tool cards) is element-local state seeded from streaming state, descriptor defaults, errors, and authoritative subtask status; once the user toggles it, parent re-renders cannot reset that choice.
-- **Nested streams replace authoritatively, then delta in place.** A subtask preview arrives through the parent tool call as a complete bounded snapshot. Existing child messages may then receive one-level deltas addressed by `parentMessageId`; a delta never invents a missing child message. The producer adds that message to its source-of-truth snapshot first.
-- **Visual grouping never changes ownership.** Consecutive tool calls use one generic chronological grid pipeline partitioned by registry layout metadata: compact tools share compact rows, subagents share only subtask rows, and full-row tools span every column. Each segment's nested repeat remains keyed by message id. Status changes never move a card to another owner; untouched projected subtasks collapse individually while the grid remains in place. Group ids remain unique through segment splits/merges and survive front-window eviction as long as one card remains.
-- **Disclosure animation is lazy and retained.** A collapsed tool body is not mounted until first use. Its first open starts from a painted closed state; later opens and closes animate the same body node, which is inert and aria-hidden while collapsed.
-- **Inline recursion is explicit and bounded.** The outer list may render subtask previews; nested lists set `allowSubtaskStreams` false. Full descendant sessions remain reachable through the drill-in event rather than recursively expanding the transcript.
-
-## Performance Optimization
-
-### DO: Debounce Expensive Operations
-
-```typescript
-private resizeTimeout: number;
-
-private handleResize = () => {
-  clearTimeout(this.resizeTimeout);
-  this.resizeTimeout = window.setTimeout(() => {
-    this.updateLayout();
-  }, 250);
-};
-```
-
-### DO: Use Observers Efficiently
-
-```typescript
-// Clean up observers
-public disconnectedCallback() {
-  super.disconnectedCallback();
-  this.resizeObserver?.disconnect();
-  this.mutationObserver?.disconnect();
-}
-```
-
-### DO: Implement Virtual Scrolling
-
-For large lists:
-
-```typescript
-// Only render visible items
-private getVisibleItems() {
-  const scrollTop = this.scrollContainer.scrollTop;
-  const containerHeight = this.scrollContainer.clientHeight;
-  const itemHeight = 50;
-  
-  const startIndex = Math.floor(scrollTop / itemHeight);
-  const endIndex = Math.ceil((scrollTop + containerHeight) / itemHeight);
-  
-  return this.items.slice(startIndex, endIndex);
-}
-```
-
-## Focus Management
-
-### DO: Handle Focus Timing
-
-```typescript
-// ✅ CORRECT - Wait for render
-async focusInput() {
-  await this.updateComplete;
-  await new Promise(resolve => requestAnimationFrame(resolve));
-  this.inputElement?.focus();
-}
-
-// ❌ INCORRECT - Focus too early
-focusInput() {
-  this.inputElement?.focus(); // Element might not exist
-}
-```
-
-### DO: Prevent Focus Loss
-
-```typescript
-// For global menus
-constructor() {
-  super();
-  // Prevent focus loss when clicking menu
-  this.addEventListener('mousedown', (e) => {
-    e.preventDefault();
-  });
-}
-```
-
-### DO: Implement Blur Debouncing
-
-```typescript
-private blurTimeout: number;
-
-private handleBlur = () => {
-  clearTimeout(this.blurTimeout);
-  this.blurTimeout = window.setTimeout(() => {
-    // Check if truly blurred
-    if (!this.contains(document.activeElement)) {
-      this.handleTrueBlur();
-    }
-  }, 100);
-};
-```
-
-## Demo System
-
-### DO: Create Comprehensive Demos
-
-Every component needs a demo:
-
-```typescript
-// dees-button.demo.ts
-import { html } from '@design.estate/dees-element';
-
-export const demoFunc = () => html`
-  <dees-button>Default Button</dees-button>
-  <dees-button type="primary">Primary Button</dees-button>
-  <dees-button type="danger" disabled>Disabled Danger</dees-button>
-`;
-
-// In component file
-import * as demoFunc from './dees-button.demo.js';
-
-export class DeesButton extends DeesElement {
-  public static demo = demoFunc.demoFunc;
-}
-```
-
-### DO: Include All Variants
-
-Show all component states and variations in demos:
-- Default state
-- Different types/variants
-- Disabled state
-- Loading state
-- Error states
-- Edge cases (long text, empty content)
-
-## Common Pitfalls and Anti-patterns
-
-### ❌ DON'T: Hardcode Z-Index Values
-
-```typescript
-// ❌ WRONG
-this.style.zIndex = '9999';
-
-// ✅ CORRECT
-this.style.zIndex = `${zIndexRegistry.getNextZIndex()}`;
-```
-
-### ❌ DON'T: Skip Base Classes
-
-```typescript
-// ❌ WRONG - Form input without base class
-export class DeesInputCustom extends DeesElement {
-  // Missing standard form functionality
-}
-
-// ✅ CORRECT
-export class DeesInputCustom extends DeesInputBase<string> {
-  // Inherits all form functionality
-}
-```
-
-### ❌ DON'T: Forget Theme Support
-
-```typescript
-// ❌ WRONG
-background-color: #ffffff;
-color: #000000;
-
-// ✅ CORRECT
-background-color: var(--dees-color-bg-primary);
-color: var(--dees-color-text-primary);
-```
-
-### ❌ DON'T: Create Components Without Demos
-
-```typescript
-// ❌ WRONG
-export class DeesComponent extends DeesElement {
-  // No demo property
-}
-
-// ✅ CORRECT
-export class DeesComponent extends DeesElement {
-  public static demo = demoFunc.demoFunc;
-}
-```
-
-### ❌ DON'T: Emit Non-Bubbling Events
-
-```typescript
-// ❌ WRONG
-this.dispatchEvent(new CustomEvent('change', {
-  detail: this.value
-}));
-
-// ✅ CORRECT
-this.dispatchEvent(new CustomEvent('change', {
-  detail: this.value,
-  bubbles: true,
-  composed: true
-}));
-```
-
-### ❌ DON'T: Skip Cleanup
-
-```typescript
-// ❌ WRONG
-public connectedCallback() {
-  window.addEventListener('resize', this.handleResize);
-}
-
-// ✅ CORRECT
-public connectedCallback() {
-  super.connectedCallback();
-  window.addEventListener('resize', this.handleResize);
-}
-
-public disconnectedCallback() {
-  super.disconnectedCallback();
-  window.removeEventListener('resize', this.handleResize);
-}
-```
-
-### ❌ DON'T: Use Inline Styles for Theming
-
-```typescript
-// ❌ WRONG
-<div style="background-color: ${this.darkMode ? '#000' : '#fff'}">
-
-// ✅ CORRECT
-<div class="themed-container">
-// In styles:
-.themed-container {
-  background-color: var(--dees-color-bg-primary);
-}
-```
-
-### ❌ DON'T: Forget Mobile Responsiveness
-
-```typescript
-// ❌ WRONG
-:host {
-  width: 800px; // Fixed width
-}
-
-// ✅ CORRECT
-:host {
-  width: 100%;
-  max-width: 800px;
-}
-
-@media (max-width: 768px) {
-  :host {
-    /* Mobile adjustments */
-  }
-}
-```
-
-## Code Examples
-
-### Example: Creating a New Button Variant
-
-```typescript
-// dees-special-button.ts
-import { customElement, property, css, html, cssManager } from '@design.estate/dees-element';
-import { DeesElement } from '@design.estate/dees-element';
-import { themeDefaultStyles } from '../00theme.js';
-import * as demoFunc from './dees-special-button.demo.js';
-
-@customElement('dees-special-button')
-export class DeesSpecialButton extends DeesElement {
-  public static demo = demoFunc.demoFunc;
-
-  @property({ type: String })
-  public text: string = 'Click me';
-
-  @property({ type: Boolean, reflect: true })
-  public loading: boolean = false;
-
-  public static styles = [
-    themeDefaultStyles,
-    cssManager.defaultStyles,
-    css`
-      :host {
-        display: inline-block;
-      }
-
-      .button {
-        padding: var(--dees-spacing-sm) var(--dees-spacing-lg);
-        background: var(--dees-color-accent-primary);
-        color: white;
-        border: none;
-        border-radius: var(--dees-radius-sm);
-        cursor: pointer;
-        transition: all var(--dees-transition-slow);
-      }
-
-      .button:hover {
-        transform: translateY(-2px);
-        box-shadow: var(--dees-shadow-md);
-      }
-
-      :host([loading]) .button {
-        opacity: 0.7;
-        cursor: not-allowed;
-      }
-    `
-  ];
-
-  public render() {
-    return html`
-      <button class="button" ?disabled=${this.loading} @click=${this.handleClick}>
-        ${this.loading ? html`<dees-spinner size="small"></dees-spinner>` : this.text}
-      </button>
-    `;
-  }
-
-  private handleClick() {
-    this.dispatchEvent(new CustomEvent('special-click', {
-      bubbles: true,
-      composed: true
-    }));
-  }
-}
-```
-
-### Example: Creating a Form Input
-
-```typescript
-// dees-input-special.ts
-export class DeesInputSpecial extends DeesInputBase<string> {
-  public static demo = demoFunc.demoFunc;
-
-  public render() {
-    return html`
-      <dees-label .label=${this.label} .required=${this.required}>
-        <input
-          type="text"
-          .value=${this.value || ''}
-          ?disabled=${this.disabled}
-          @input=${this.handleInput}
-          @blur=${this.handleBlur}
-        />
-      </dees-label>
-    `;
-  }
-
-  private handleInput(e: Event) {
-    this.value = (e.target as HTMLInputElement).value;
-    this.changeSubject.next(this);
-  }
-
-  private handleBlur() {
-    this.dispatchEvent(new CustomEvent('blur', {
-      bubbles: true,
-      composed: true
-    }));
-  }
-
-  public getValue(): string {
-    return this.value;
-  }
-
-  public setValue(value: string): void {
-    this.value = value;
-    this.changeSubject.next(this);
-  }
-}
-```
-
-## Summary
-
-This playbook represents the collective wisdom and patterns found in the @design.estate/dees-catalog component library. Following these guidelines will help you create components that are:
-
-- **Consistent**: Following established patterns
-- **Maintainable**: Easy to understand and modify
-- **Performant**: Optimized for real-world use
-- **Accessible**: Usable by everyone
-- **Theme-aware**: Supporting light and dark modes
-- **Well-integrated**: Working seamlessly with the component ecosystem
-
-Remember: When in doubt, look at existing components for examples. The codebase itself is the best documentation of these patterns in action.