@pnx-mixtape/mxds 0.1.0-rc.3 → 0.1.0-rc.5

package/docs/ComponentArchitecture.md

@@ -0,0 +1,714 @@
+# Component Architecture
+
+This guide explains how to structure and build components in the Mixtape Design System.
+
+## Table of Contents
+
+- [Component Types](#component-types)
+- [Web Components](#web-components)
+- [React Components](#react-components)
+- [Twig Templates](#twig-templates)
+- [Figma Code Connect](#figma-code-connect)
+- [File Organization](#file-organization)
+- [Props & Types](#props--types)
+- [Common Patterns](#common-patterns)
+- [Best Practices](#best-practices)
+
+---
+
+## Component Types
+
+The design system supports three component formats:
+
+1. **Web Components** (Custom Elements) - For framework-agnostic JavaScript
+2. **React Components** - For React applications
+3. **Twig Templates** - For Drupal integration
+
+Most components provide all three formats for maximum flexibility.
+
+---
+
+## Web Components
+
+### Structure Pattern
+
+```typescript
+/**
+ * ComponentName
+ * @file Brief description of what the component does
+ */
+
+import { makeAnchor } from "../../../Utility/utilities"
+
+export default class ComponentName extends HTMLElement {
+  // 1. Properties
+  internals_: ElementInternals
+  controller: AbortController
+  // ... other properties
+
+  // 2. Constructor
+  constructor() {
+    super()
+    this.internals_ = this.attachInternals()
+    this.controller = new AbortController()
+  }
+
+  // 3. Lifecycle Methods
+  connectedCallback(): void {
+    if (!this.trigger || !this.target) return
+
+    const { signal } = this.controller
+    // Setup event listeners with signal
+    this.trigger.addEventListener("click", this.handleClick, { signal })
+  }
+
+  disconnectedCallback(): void {
+    // Cleanup - ALWAYS implement this
+    this.controller.abort()
+    this.observer?.disconnect()
+    clearTimeout(this.timeout)
+  }
+
+  // 4. Event Handlers (use arrow functions)
+  handleClick = (): void => {
+    // Handler logic
+  }
+
+  // 5. Getters (with validation)
+  get trigger(): HTMLButtonElement {
+    const trigger = this.querySelector("button")
+    if (!trigger) {
+      throw new Error(`${this.localName} must contain a <button>`)
+    }
+    return trigger
+  }
+
+  // 6. Helper Methods
+  private generatedId(): string {
+    return makeAnchor(this.textContent || "component")
+  }
+  // generatedId() wraps makeAnchor() to produce a stable HTML-safe ID.
+  // See API.md → generatedId() for details.
+}
+
+// 7. Register the component
+if (!customElements.get("mx-component")) {
+  customElements.define("mx-component", ComponentName)
+}
+
+// 8. TypeScript declaration
+declare global {
+  interface HTMLElementTagNameMap {
+    "mx-component": ComponentName
+  }
+}
+```
+
+### Key Requirements
+
+1. **Always extend HTMLElement**
+2. **Use ElementInternals** for form-associated components
+3. **Use AbortController** for event listener cleanup
+4. **Store observers** as properties (iO, rO, mO)
+5. **Implement disconnectedCallback()** for cleanup
+6. **Validate DOM queries** in getters with error messages
+7. **Use arrow functions** for event handlers (preserves `this`)
+8. **Register with custom name** (mx-prefix)
+9. **Add TypeScript declarations**
+
+### Example: Accordion Component
+
+```typescript
+export default class Accordion extends HTMLElement {
+  internals_: ElementInternals
+  controller: AbortController
+
+  constructor() {
+    super()
+    this.internals_ = this.attachInternals()
+    this.controller = new AbortController()
+  }
+
+  connectedCallback(): void {
+    if (!this.details || !this.trigger) return
+
+    const { signal } = this.controller
+    document.addEventListener("beforeprint", this.handleOpen, { signal })
+    document.addEventListener("afterprint", this.handleClose, { signal })
+    this.handleHash()
+    document.addEventListener("hashchange", this.handleHash, { signal })
+  }
+
+  disconnectedCallback(): void {
+    this.controller.abort()
+  }
+
+  handleOpen = (): void => {
+    if (!this.details) return
+    this.details.open = true
+  }
+
+  handleClose = (): void => {
+    if (!this.details) return
+    this.details.open = false
+  }
+
+  handleHash = (): void => {
+    const { hash } = window.location
+    if (hash && hash === `#${this.details?.id}`) {
+      this.handleOpen()
+    }
+  }
+
+  get details(): HTMLDetailsElement | null {
+    const details = this.querySelector("details")
+    if (!details) {
+      throw new Error(`${this.localName} must contain a <details> element.`)
+    }
+    details.id = details.id || this.generatedId()
+    return details
+  }
+
+  get trigger(): HTMLElement | null {
+    return this.details?.querySelector("summary")
+  }
+
+  private generatedId(): string {
+    const text = this.trigger?.textContent || this.textContent || "accordion"
+    return makeAnchor(text)
+  }
+}
+```
+
+---
+
+## React Components
+
+### Structure Pattern
+
+```typescript
+import { JSX, PropsWithChildren } from "react"
+import classNames from "classnames"
+import { AsTypes } from "@pnx-mixtape/ids-shape"
+import { BackgroundStyles } from "../../enums"
+
+// 1. Type Definition
+type ComponentProps = PropsWithChildren & {
+  // Optional props with defaults
+  reversed?: boolean
+  block?: boolean
+  // Props with type constraints
+  as?: AsTypes
+  background?: BackgroundStyles
+  // Optional string props
+  className?: string
+}
+
+// 2. Component with destructured props
+const Component = ({
+  children,
+  reversed = false,  // Default values
+  block = false,
+  as = AsTypes.DIV,
+  background = null,
+  className = null,
+}: ComponentProps): JSX.Element => {
+  // 3. Dynamic element type
+  const Tag: JSX.ElementType = `${as}` as unknown as JSX.ElementType
+
+  return (
+    <Tag className="mx-container">
+      <article
+        className={classNames("mx-component", className, {
+          "mx-component--reversed": reversed,
+          "mx-component--block": block,
+          [`mx-background--${background}`]: background,
+        })}
+      >
+        {children}
+      </article>
+    </Tag>
+  )
+}
+
+export default Component
+```
+
+### Key Requirements
+
+1. **Use TypeScript types** for all props
+2. **Extend PropsWithChildren** if accepting children
+3. **Provide default values** in destructuring
+4. **Use classNames library** for conditional classes
+5. **Return JSX.Element** type explicitly
+6. **Export as default**
+7. **Use semantic HTML** elements
+
+### Example: Card Component
+
+```typescript
+import { JSX, PropsWithChildren } from "react"
+import classNames from "classnames"
+import { BackgroundStyles } from "../../enums"
+import { AsTypes } from "@pnx-mixtape/ids-shape"
+
+type CardProps = PropsWithChildren & {
+  reversed?: boolean
+  block?: boolean
+  as?: AsTypes
+  background?: BackgroundStyles
+  className?: string
+}
+
+const Card = ({
+  children,
+  reversed = null,
+  block = false,
+  as = AsTypes.DIV,
+  background = null,
+  className = null,
+}: CardProps): JSX.Element => {
+  const Tag: JSX.ElementType = `${as}` as unknown as JSX.ElementType
+
+  return (
+    <Tag className="mx-container">
+      <article
+        className={classNames("mx-card", className, {
+          "mx-card--reversed": reversed,
+          "mx-card--block": block,
+          [`mx-background--${background}`]: background,
+        })}
+      >
+        {children}
+      </article>
+    </Tag>
+  )
+}
+
+export default Card
+```
+
+---
+
+## Twig Templates
+
+### Structure Pattern
+
+```twig
+{% set baseClass = 'mx-component' %}
+{% set classes = [baseClass] %}
+{% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+
+<div{{ attributes }}>
+  {{ content }}
+</div>
+```
+
+### Key Requirements
+
+1. **Use `create_attribute()`** for the root element's attributes, merging any passed-in `attributes`
+2. **Prefer semantic HTML** elements, matching the equivalent React/Web Component markup
+3. **Be selective with `{% for %}` loops** — see below, this is the most common way a Twig template breaks Drupal Canvas compatibility
+
+### Avoid `{% for %}` loops over repeatable content
+
+These Twig templates are the source that gets wrapped as Drupal Canvas (Experience Builder) components. Canvas's slot model hands a template **one pre-rendered value per slot**, never an array to iterate — an editor drops multiple blocks into a region, and Drupal concatenates their rendered output before the template ever sees it. A `{% for item in items %}` loop assumes the opposite (an array prop it can iterate), which breaks under Canvas: printing an array directly (`{{ items }}` without joining first) renders as the literal word `Array` in real Drupal/PHP Twig, or inserts stray commas in the Twig.js engine Storybook uses.
+
+- **Never accept an array prop for repeatable content.** Take a single pre-joined string instead, and print it directly — `{{ items }}`, no `for`, no `join`, no `raw`. Build that string at the call site: `.stories.ts` files join an array of already-rendered items before passing them as an arg, e.g. `items: [AccordionItem({...}), AccordionItem({...})].join("")`.
+- **If each item needs its own wrapper element** (e.g. `<li>`, a slide container), give that wrapper its own sibling sub-component rather than generating it from a loop in the parent. See `accordion-item.twig`, `tab-item.twig`, and `tag-item.twig`: the parent template is just `{{ items }}`, and each item component owns its complete root element, wrapper included.
+- **`{% for %}` loops over a scalar array are fine** — e.g. building CSS modifier classes from a `modifiers: string[]` prop. This rule is about repeatable *content* (things an editor would add/remove/reorder as blocks), not plain data.
+- **Exceptions**: native/technical markup that isn't a Canvas-editable "list" — `<option>` in a `<select>`, `<source>` in a `<picture>` — can keep a loop; these aren't things an editor rearranges as blocks.
+
+```twig
+{# accordion.twig — parent, no loop #}
+<div class="mx-accordions">
+  {{ items }}
+</div>
+```
+
+```twig
+{# accordion-item.twig — owns its own <details> root, including any wrapper #}
+<mx-accordion>
+  <details{{ attributes }}>
+    <summary class="mx-accordion__toggle">{{ title }}</summary>
+    <div class="mx-accordion__content">{{ content }}</div>
+  </details>
+</mx-accordion>
+```
+
+---
+
+## Figma Code Connect
+
+Every component with a React implementation has a matching `Component.figma.ts` — a [Figma Code Connect](https://www.figma.com/code-connect-docs/) mapping that lets designers copy real component code straight from the Figma frame. It maps the React component only (`source` always points at the `.tsx` file); Twig/Web-Component variants aren't represented in Figma.
+
+### Structure Pattern
+
+```typescript
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=65-234
+// source=src/Component/Tag/Tag.tsx
+// component=Tag
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const dismissible = instance.getEnum("Dismissible", { Off: false, On: true })
+
+// Real children — a proper Content SLOT (not a fixed text layer)
+const content = instance.getSlot("Content")
+
+export default {
+  example: figma.code`<Tag>${content}</Tag>`,
+  imports: ['import { Tag } from "@pnx-mixtape/mxds/react"'],
+  id: "tag",
+  metadata: {
+    nestable: true,
+  },
+}
+```
+
+- **Header comments** (`url`/`source`/`component`) are read by the Figma Code Connect CLI — `url` must point at the real frame's node, not a placeholder.
+- **`figma.selectedInstance`** reads the actual Figma layer's variant properties (`getEnum`, `getBoolean`, `getSlot`, `getInstanceSwap`, …) so the exported snippet reflects whatever variant a designer has selected.
+- **A slot must be interpolated directly inside the `figma.code` tagged template**, never assigned through an untagged intermediate string first — doing so passes `tsc` but silently renders as `[object Object]` in the real published snippet.
+- **`id`** is the kebab-case component id used by the Figma library; `metadata.nestable` marks whether the component can be nested inside another mapped component's slot.
+
+`tools/scaffold-component.mjs` generates a **shell only** — `url=TODO`, no real `getEnum`/`getSlot` calls — since those depend on the actual Figma frame. Populate it for real using the `code-to-figma-code-connect` skill rather than guessing the shape; it also covers validating (`figma connect parse`) and publishing.
+
+---
+
+## File Organization
+
+### Component Directory Structure
+
+```
+Component/
+├── README.md                    # Component documentation
+├── Component.tsx                # React component
+├── Component.stories.tsx        # React Storybook stories
+├── Component.figma.ts           # Figma Code Connect mapping (React only)
+├── component.twig              # Twig template
+├── Component.stories.ts        # Twig Storybook stories
+├── component.css               # Public CSS API
+├── _component-partial.css      # Internal CSS
+├── Elements/                   # Web Components (if needed)
+│   └── ComponentElement.ts
+├── Components/                 # Sub-components (if needed)
+│   └── ComponentPart.tsx
+└── __snapshots__/             # Visual regression tests
+    ├── Component.stories.ts.snap
+    └── Component.stories.tsx.snap
+```
+
+### File Naming Conventions
+
+- **React**: `PascalCase.tsx` (Component.tsx)
+- **Web Components**: `PascalCase.ts` (Accordion.ts)
+- **Twig**: `kebab-case.twig` (accordion.twig)
+- **CSS**: `kebab-case.css` (accordion.css)
+- **Partials**: `_kebab-case.css` (_accordion-base.css)
+- **Stories**: Match component name + `.stories.ts/tsx`
+- **Figma Code Connect**: `PascalCase.figma.ts` (Component.figma.ts) — only for components with a React implementation
+
+---
+
+## Props & Types
+
+### Type Definitions
+
+```typescript
+import { PropsWithChildren } from "react"
+import { AsTypes } from "@pnx-mixtape/ids-shape"
+
+// Simple props
+type SimpleProps = {
+  title: string
+  active: boolean
+}
+
+// With children
+type WithChildrenProps = PropsWithChildren & {
+  className?: string
+}
+
+// With element type
+type FlexibleProps = PropsWithChildren & {
+  as?: AsTypes
+}
+
+// With union types
+type VariantProps = {
+  variant: "primary" | "secondary" | "tertiary"
+  size: "small" | "medium" | "large"
+}
+
+// With optional complex types
+type ComplexProps = PropsWithChildren & {
+  background?: BackgroundStyles
+  modifiers?: ButtonModifiers[]
+  onClick?: (event: MouseEvent) => void
+}
+```
+
+### Default Values
+
+```typescript
+// ✅ Good - Defaults in destructuring
+const Component = ({
+  variant = "primary",
+  size = "medium",
+  active = false,
+}: Props) => {
+  // ...
+}
+
+// ❌ Avoid - Defaults in type definition (TypeScript only, not runtime)
+type Props = {
+  variant?: "primary" | "secondary" // No default here
+}
+```
+
+---
+
+## Common Patterns
+
+### Disclosure Pattern
+
+Used in: AccordionDiv, GlobalToggle, Navigation submenus (web component); Accordion, Header, Navigation DropdownLevel (React)
+
+**Web component** — `DisclosureWidget` handles the toggle/attribute bookkeeping:
+
+```typescript
+import { DisclosureWidget } from "../../../Utility/utilities"
+
+connectedCallback(): void {
+  this.widget = new DisclosureWidget(this.trigger, this.target)
+  this.widget.init()
+
+  const { signal } = this.controller
+  this.trigger.addEventListener('disclosure-toggle', this.handleToggle, { signal })
+}
+
+handleToggle = ({ detail }: CustomEvent<DisclosureWidgetEvent>): void => {
+  const { isOpen } = detail
+  // Handle state change
+}
+```
+
+**React** — `useDisclosureState` (react-stately) tracks the boolean; we hand-write the button/panel markup and `aria-expanded`/`inert` wiring ourselves rather than using the full `useDisclosure` hook (see [React Aria / React Stately](#react-aria--react-stately) below for why):
+
+```typescript
+import { useDisclosureState } from "react-stately"
+
+const { isExpanded, toggle } = useDisclosureState({ defaultExpanded: false })
+
+return (
+  <>
+    <button aria-expanded={isExpanded} onClick={() => toggle()}>...</button>
+    <div inert={!isExpanded}>...</div>
+  </>
+)
+```
+
+### Keyboard Navigation Pattern
+
+Used in: Navigation flyout menus (`Keyboard` utility), DropMenu (`moveFocus`) — both web component; DropMenu, Tabs (React)
+
+**Web component** — the shared `Keyboard` utility handles roving focus between links. `Navigation/Elements/Navigation.ts` is currently its only consumer — don't reach for it in new web components without a specific reason, prefer a small dedicated implementation instead. `DropMenu/Elements/DropMenu.ts`'s `moveFocus` is an example of that smaller alternative: a few lines of index math scoped to its own item list, rather than a shared class:
+
+```typescript
+import { Keyboard } from "../../../Utility/utilities"
+
+const keyboard = new Keyboard()
+
+useEffect(() => {
+  if (!containerRef.current || !open) return
+
+  const items = containerRef.current.querySelectorAll("button")
+  keyboard.attachMenu(containerRef.current, items)
+
+  const controller = new AbortController()
+  keyboard.attachEventListeners(controller.signal)
+
+  return () => {
+    controller.abort()
+    keyboard.detachMenu()
+  }
+}, [open])
+```
+
+**React** — wrap the container in a `FocusScope`, then call `useFocusManager()` from each item to move focus in response to arrow keys:
+
+```typescript
+import { FocusScope, useFocusManager } from "react-aria"
+
+// Container:
+<FocusScope>{children}</FocusScope>
+
+// Each item:
+const focusManager = useFocusManager()
+const onKeyDown = (event: KeyboardEvent) => {
+  switch (event.key) {
+    case "ArrowDown":
+      focusManager?.focusNext({ wrap: true, tabbable: true })
+      break
+    case "ArrowUp":
+      focusManager?.focusPrevious({ wrap: true, tabbable: true })
+      break
+  }
+}
+```
+
+> `tabbable: true` matters if any item can have `tabindex="-1"` (e.g. hidden/disabled) — the default "focusable" mode would otherwise still stop on them. Omit it for roving-tabindex widgets like Tabs, where non-active items are `tabindex="-1"` by design and *should* still be reachable by arrow keys.
+
+### React Aria / React Stately
+
+Before reaching for a react-aria/react-stately hook, check whether it does more than you asked for. Several of the higher-level "behavior" hooks assume a floating-overlay UI and carry side effects that don't fit this design system's Twig-parity, own-your-markup model:
+
+- **Prefer the *state* hook (react-stately) over the matching *behavior* hook (react-aria) when the behavior hook assumes conventions we don't use.** `useDisclosureState` just tracks a boolean; the full `useDisclosure` hook imperatively toggles `hidden="until-found"` and injects `--disclosure-panel-width`/`--disclosure-panel-height` inline styles for its own animation model — which fights our CSS-driven `[data-open]`/`inert` collapse. `useComboBoxState` builds the collection/selection bookkeeping; `useComboBox` additionally calls `ariaHideOutside()` whenever open, `aria-hide`-ing the *entire rest of the page* — correct for a floating popover, wrong for an inline listbox like `Autocomplete`'s.
+- **Check what a hook's returned methods actually alias to before using them** — a method's name doesn't always match its documented behavior. `useComboBoxState`'s `close` is aliased to `commitValue`, which resets the input to whatever the internal selection-key system thinks is "selected" — surprising if you handle selection yourself and never populate that system (as `Autocomplete` does). Read the hook's source, not just its `.d.ts`, when something behaves unexpectedly.
+- **Verify empirically, not just by types.** Several of the surprises above only show up in rendered DOM or test output, not the type signatures — run the component's play-function tests (or open it in Storybook) after adopting a new hook.
+
+### Observer Pattern
+
+Used in: Carousel, Sticky, IntersectionLoader
+
+```typescript
+connectedCallback(): void {
+  // IntersectionObserver
+  this.iO = new IntersectionObserver(entries => {
+    entries.forEach(({ isIntersecting }) => {
+      if (isIntersecting) this.load()
+    })
+  })
+  this.iO.observe(this.element)
+
+  // ResizeObserver
+  this.rO = new ResizeObserver(entries => {
+    entries.forEach(() => this.handleResize())
+  })
+  this.rO.observe(this.element)
+}
+
+disconnectedCallback(): void {
+  this.iO?.disconnect()
+  this.rO?.disconnect()
+}
+```
+
+### Lazy Loading Pattern
+
+Used in: IntersectionLoader, BreakpointLoader
+
+```typescript
+import { IntersectionLoader } from "../../../Utility/utilities"
+
+// Load component on intersection
+IntersectionLoader.create("[data-lazy]", async () => {
+  const { default: Component } = await import("./Component")
+  // Initialize component
+})
+
+// Load component at breakpoint
+import { BreakpointLoader } from "../../../Utility/utilities"
+
+BreakpointLoader.create(
+  "[data-responsive]",
+  async () => {
+    const { default: Component } = await import("./Component")
+    // Initialize component
+  },
+  { mediaQuery: "(min-width: 768px)" },
+)
+```
+
+### Effect Timing Pattern (`useEffect` vs `useLayoutEffect`)
+
+Used in: Filters (right-variant resize-reopen), Tabs (URL `?tab=` sync), Accordion (URL `#hash` deep-link), PaginationContext (URL `?page=` sync on load), Dialog + Gallery (imperative `showModal()`/`close()` + scroll-to-slide), Autocomplete (scroll the active option into view) — all React.
+
+If a `useEffect` sets state (or calls an imperative DOM API) whose result is part of the *same render's* visible output, the browser can paint the stale value for one frame before the effect corrects it — a real, if brief, flash of wrong content: a tab that briefly shows the wrong panel before a `?tab=` URL param corrects it, an accordion that renders closed before a `#hash` deep-link expands it, a dialog that pops open at the wrong scroll position for a frame before jumping to the right slide. Use `useIsomorphicLayoutEffect` (`src/Utility/Hooks/useIsomorphicLayoutEffect.ts`) instead of a bare `useEffect` for these — it's `useLayoutEffect` in the browser (runs before paint) and falls back to `useEffect` during server rendering. The isomorphic fallback matters here specifically: a bare `useLayoutEffect` logs a React warning if it ever actually executes on the server, and SSR/hydration is a real, documented consumption pattern for this library (see [Troubleshooting.md](./Troubleshooting.md)'s "React hydration errors" section) — don't import `useLayoutEffect` from `"react"` directly in a component.
+
+```typescript
+import useIsomorphicLayoutEffect from "../../Utility/Hooks/useIsomorphicLayoutEffect"
+
+useIsomorphicLayoutEffect(() => {
+  // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
+  // oxlint-disable-next-line react/set-state-in-effect -- synchronizes state with the URL, an external system
+  setActiveTab(tabParam)
+}, [tabParam])
+```
+
+Web Components don't need this distinction — `connectedCallback`/`attributeChangedCallback` already run synchronously as part of the DOM update, with no passive-vs-layout effect split to get wrong.
+
+**Only convert effects with a genuine flash risk.** Most effects — data fetching, subscribing to events, async measurement, cleanup-only — are correctly `useEffect` and gain nothing from running earlier. A cautionary tale: an attempt to fix Carousel's initial nav-button visibility this way backfired. Carousel already measures overflow via a `ResizeObserver`, whose first callback fires close to paint time on its own; adding a *second*, layout-effect-driven call to the same measurement duplicated that work, and for the pagination/counter variants it duplicated an untracked `setTimeout` per mount too — which measurably delayed unrelated stories' tests when several ran together in the same file. That change was reverted. Don't reach for `useIsomorphicLayoutEffect` where a native API (an observer, a browser default) already does the same measurement early enough on its own — only add it where nothing else does.
+
+---
+
+## Best Practices
+
+### Do's ✅
+
+1. **Use semantic HTML** - `<nav>`, `<main>`, `<article>`, `<section>`
+2. **Validate DOM queries** - Throw errors with helpful messages
+3. **Generate IDs when missing** - Use makeAnchor utility
+4. **Clean up resources** - Always implement cleanup
+5. **Use arrow functions** for handlers - Preserves `this` binding
+6. **Add ARIA attributes** - Support screen readers
+7. **Support keyboard navigation** - Tab, Enter, Escape, Arrows
+8. **Document props** - JSDoc comments for complex props
+9. **Write stories** - For every component variant
+10. **Test accessibility** - Use Storybook a11y addon
+
+### Don'ts ❌
+
+1. **Don't forget cleanup** - Always disconnect observers
+2. **Don't use inline styles** - Use CSS classes
+3. **Don't hardcode IDs** - Generate or allow customization
+4. **Don't ignore errors** - Log in development, handle in production
+5. **Don't use `any` type** - Use proper TypeScript types
+6. **Don't nest BEM classes** - Keep selectors flat
+7. **Don't mutate props** - Props are read-only
+8. **Don't use `innerHTML`** - XSS vulnerability
+9. **Don't forget mobile** - Mobile-first responsive design
+10. **Don't skip documentation** - Update README with changes
+11. **Don't loop over repeatable content in Twig** - Pass a pre-joined string instead; see [Twig Templates](#twig-templates)
+12. **Don't use a bare `useEffect` when it sets state that's part of the same render's visible output** - use `useIsomorphicLayoutEffect` instead, and don't duplicate a measurement a native observer/API already does early on its own; see [Effect Timing Pattern](#effect-timing-pattern-useeffect-vs-uselayouteffect)
+
+---
+
+## Component Checklist
+
+Before submitting a new component, verify:
+
+- [ ] TypeScript types defined
+- [ ] Props have defaults where appropriate
+- [ ] Cleanup implemented (disconnectedCallback/useEffect cleanup)
+- [ ] Input validation using validators utility
+- [ ] Error handling with try-catch
+- [ ] Environment-specific logging
+- [ ] BEM class names
+- [ ] Responsive styles with custom media
+- [ ] Logical CSS properties
+- [ ] ARIA labels and roles
+- [ ] Keyboard navigation support
+- [ ] React component (if applicable)
+- [ ] Web Component (if applicable)
+- [ ] Twig template (if applicable) — repeatable content passed as a joined string, not an array/`{% for %}` loop
+- [ ] Storybook stories created
+- [ ] README documentation
+- [ ] Snapshot tests passing
+- [ ] No TypeScript errors
+- [ ] Linting passes (`pnpm lint`)
+- [ ] Manual testing in Storybook
+- [ ] Accessibility tested (a11y addon)
+- [ ] Mobile tested
+- [ ] Cross-browser tested
+
+---
+
+## Related Documentation
+
+- [Code Quality Guidelines](./CodeQuality.md)
+- [Memory Management](./MemoryManagement.md)
+- [CSS Guidelines](./CSSGuidelines.md)
+- [Testing Guide](./Testing.md)
+- [API Documentation](./API.md)