# Breakpoints

## Essence

Viewport-width range contract for every Design System item.

`Breakpoints` define ranges of browser/window width used to inspect component and token behavior across responsive contexts.

## Hook

Use whenever a Design System component, token, rule, or page template is previewed or reviewed.

## Internal Rules

- Every Design System item has a breakpoint context.
- Components have breakpoints.
- Tokens have breakpoints.
- Rules and page templates have breakpoints when rendered inside Component Page Template.
- Breakpoints define window-width ranges only.
- Breakpoints do not define columns, layout density, reading width, or page composition rules.
- Approved ranges are `Mobile`, `Tablet`, `Desktop`, and `Ultra-wide`.
- Breakpoint switcher appears first in Component Page Template controls.
- Current components keep the same component contract across all breakpoints.
- Do not add breakpoint-specific variants or styles until they are explicitly designed.

## Current Tokens

- `--breakpoint-mobile-min: 0px`.
- `--breakpoint-mobile-max: 639px`.
- `--breakpoint-tablet-min: 640px`.
- `--breakpoint-tablet-max: 1023px`.
- `--breakpoint-desktop-min: 1024px`.
- `--breakpoint-desktop-max: 1439px`.
- `--breakpoint-ultra-wide-min: 1440px`.

## Use When

- Previewing any component.
- Previewing any token page.
- Checking whether behavior changes by viewport width.
- Documenting responsive behavior for future component variants.

## Do Not Use When

- The decision is about layout columns.
- The decision is about content max width.
- The decision is about typography scale.
- The decision is about spacing or density.
- A component needs local responsive behavior that has not been approved.

## Exception Rule

If a component or token needs a new named breakpoint range:

- stop implementation;
- explain what viewport-width behavior is missing;
- propose the breakpoint name and pixel range;
- ask for user/design-system approval before adding it.

## Edge Cases

- Components may behave identically across all four ranges until responsive variants are designed.
- The switcher records the selected range but does not resize Preview.
- All previews remain full width and keep the same layout until breakpoint-specific component designs are approved.
- Do not use breakpoint names as shortcuts for layout rules.
- If responsive layout behavior is needed, document it separately from the breakpoint range.

## Accessibility Notes

- Breakpoint previews should help catch wrapping, overflow, and hit-area issues.
- Token behavior should still be reviewed at small and large widths even when the token value itself does not change.

## Related Components And Patterns

- `Component Page Template`: always renders Breakpoint as the first prop switcher.
- `Prop Switcher`: renders the Breakpoint control.
- `Preview`: displays the item inside the selected breakpoint context.
- `Spacing`, `Typography`, `Colors`, `Icons`: token pages still have breakpoint context.

## Code Paths

- `packages/design-system/src/styles/tokens.css`
- `packages/design-system/src/components/ComponentPreview.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`