Rules Hub
Coding Rules Library
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
Choose container vs viewport measurement deliberately in embeddable components
A reusable/embeddable component (web component, widget) can sit in containers of arbitrary width, so responsive behavior should default to measuring its own container, not the viewport. Switch to a viewport media query only when the layout decision is explicitly tied to the page's breakpoint by design, and say so - and don't mix the two strategies for related concerns without a stated reason.
Bad example
| 1 | const isCompact = useMediaQuery('(max-width: 767px)'); // widget can be 300px wide on a desktop viewport |
Explanation (EN)
Viewport width says nothing about the space the embedded widget actually has, so a narrow embed on a wide viewport renders the wide layout and squishes.
Objašnjenje (HR)
Good example
| 1 | const width = useContainerWidth(ref); // ResizeObserver |
| 2 | const isCompact = width < COMPACT_MAX_WIDTH; |
Explanation (EN)
Container-based by default; viewport-based only as an explicit, documented design contract.
Objašnjenje (HR)
Notes (EN)
Container width cannot discriminate cases where width ranges overlap with opposite expected outcomes (e.g. a full-width mobile card wider than a desktop half-width card). That is the signal the decision belongs to the page breakpoint, not the container. When both strategies exist in one component, leave a comment on why they differ.
Exceptions / Tradeoffs (EN)
A variant that is opt-in for one specific page placement may follow that page's breakpoints directly.