ux-ui-maxpro

app/globals.css

The one rule

1. Extract a spec from the reference

• Structure: how many regions (top bar, sidebar, content), and each region's width/height. Note whether the top bar has a border/shadow/blur or is flush with the page background.
• Grid: column count at the widest breakpoint, gutter size, and how it steps down (4 → 3 → 2 → 1). For masonry, note whether card heights vary and by how much — that varied rhythm is usually the whole point.
• Cards / tiles: corner radius, surface color, border vs borderless, shadow vs flat, overlay elements (avatars, buttons) with their size and inset from the corner.
• Type: size, weight, and color for each text role (title, tagline, meta, nav link). Note when two roles sit inline on one baseline (e.g. bold title + gray tagline).
• Pills / controls: capsule height, horizontal padding, gap, and the active-vs-inactive treatment (a black/white inversion is common).
• Color: sample the exact surface grays and accents. They are rarely pure

  #fff

  /

  #000

  .

2. Map every element to honest data

aria-label

title

aria-pressed

3. Style through tokens, never hex

app/globals.css

• Add the raw value to both

  :root

  (light) and

  .dark

  (dark) — a dark peer is mandatory, even when the reference is light-only; tune the dark value by eye.
• Register it under

  @theme inline

  (

  --color-<name>: var(--<name>)

  ) so a

  bg-<name>

  /

  text-<name>

  utility exists.
• If the exact look requires a documented deviation from DESIGN.md (capsule buttons, blur chips, a borderless card), add a short amendment to DESIGN.md so the next contributor does not "fix" it back.

4. Masonry recipes

• CSS columns (

  columns-N

  , children

  break-inside-avoid mb-*

  ) is the default: it packs top-to-bottom per column, SSRs with zero layout shift, and — crucially — keeps every card in one DOM parent, so a stable React

  key

  preserves a card's mounted state across filtering and sorting. Use it unless the design truly needs left-to-right row order.
• JS balanced columns (measure heights, place into the shortest column) gives row-major order but costs a first-paint measurement pass and remounts children across column parents. Only reach for it when row order is a hard requirement.
• Manufacturing a varied rhythm: when the source media is uniform (e.g. all 16:9), assign each card a deterministic tile shape by a stable function of its index/slug so the shape never changes when the list is filtered or reordered. Center the real media contained on the tile's surface (never crop unless the user opts into cropping) — compute which dimension binds from the static tile-ratio vs media-ratio comparison.

5. Heavy-media grids

IntersectionObserver

rootMargin: "200px 0px"

6. Verify by overlay, in both themes

• Run the app and screenshot the built page at the reference's exact breakpoints.
• Overlay the two at ~50% opacity (or place side by side) and check every measured number: bar height, baseline alignment, pill height and gaps, gutters, card radius, overlay size/inset.
• Resize through each breakpoint boundary and confirm the column count steps as specified.
• Toggle light/dark and confirm every new token reads correctly in both.
• Tab through the keyboard path (pills → controls → cards) and confirm focus rings + ARIA.
• Open the sibling pages you did not intend to change and confirm they are byte-identical — shared chrome edits leak easily.