Skip to content

Styling ​

pd-components ships zero visual design — no colors, no spacing, no transitions from JS (SPEC §1.2, rule 3). Every component's only job is to keep a small set of plain HTML attributes truthful: open, data-state, inert, hidden, and aria-expanded/aria-pressed on the invoker buttons that target it (see the state contract if you haven't read it yet). Styling is entirely selector work against those attributes — there is no component API, no CSS custom properties to configure, no theme object. This page covers the two first-class ways to write those selectors, a cookbook for enter/exit animation, and the grid-first layout rule that governs every recipe in these docs.

The two styling paths ​

Both paths read the same hooks. Pick one per project (or mix — nothing here is Tailwind-specific at the component level).

HookVanilla CSSTailwind
Logical open statepd-disclosure[open]open:* (Tailwind's boolean-attribute variant)
Presentation statepd-nav-panel[data-state="open"]data-[state=open]:*
Invoker's expanded statebutton[aria-expanded="true"]aria-expanded:* (built-in ARIA-state variant)
Active filter buttonbutton[aria-pressed="true"]aria-pressed:*
Closed/inactive interaction[inert] (managed synchronously by the component)Native; no utility needed
Closed/inactive visibility[hidden] after exit animation (needs display:none!important — see getting started)Tailwind's preflight already sets this; no action needed
A sibling reacting to a descendant's statepd-nav-panel:has([data-state="open"]), or plain nestinghas-* arbitrary variant, or group/group-data-*

Prefer data-state over open/aria-expanded for animation-driving selectors: it's the one attribute every disclosure-like element guarantees is present immediately after connect (SPEC §3), it has more than two values across the library ("active"/"inactive" on drilldown panels, "visible"/"hidden" on the header), and — critically for exit animations — it flips to "closed" before hidden lands, giving CSS a committed frame to transition away from. open and aria-expanded are still worth styling directly for simple, non-animated affordances (a chevron rotation keyed on aria-expanded needs no data-state at all, as the disclosure and nav recipes below show).

Vanilla CSS ​

Nothing but attribute selectors — no classes the component ever adds or removes for you to hook into to begin with:

css
pd-disclosure[data-state='closed'] { /* … */ }
pd-nav-panel[data-state='open'] { /* … */ }
button[commandfor][aria-expanded='true'] { /* … */ }
pd-filter button[aria-pressed='true'] { /* … */ }

Tailwind ​

Tailwind v4's arbitrary attribute variant (data-[state=open]:) and its built-in ARIA-state variants (aria-expanded:, aria-pressed:, aria-selected:, …) cover every hook above without a plugin. group/group-data-* reaches from a state-bearing element to a styled descendant when nesting alone isn't enough (e.g. tinting a whole <li> while the pd-nav-panel inside it is open, where the panel and the element you want to style aren't in an ancestor/descendant relationship convenient for :has):

html
<li class="group">
  <pd-nav-panel data-pd-group class="data-[state=open]:block">…</pd-nav-panel>
  <span class="hidden group-has-[[data-state=open]]:inline">Open</span>
</li>

group-has-[[data-state=open]]:* composes group with the has-* variant, so the marker span reacts to the panel's state without either element needing a class the component doesn't already provide a hook for.

Grid-first layout (SPEC §1.2) ​

Every layout recipe in these docs reaches for display: grid first, and only drops to flex for content that is genuinely one-dimensional and has no need for the two axes grid gives you for free. The rule exists for two reasons, not just taste:

  1. No wrapper tax. pd-components is flat markup by design — no library element wraps a trigger and a panel just so something can be display: flex. Grid's grid-template-columns/-rows and grid-column/grid-row let you place children (including children that are siblings only because the invoker/target relationship is expressed through commandfor, not nesting) into a two-dimensional layout with zero extra elements — exactly the constraint the components themselves are built to.
  2. Mega-menu columns are inherently 2D. A pd-nav-panel's content is a grid of link columns (and often a promo tile spanning more than one), a drawer's dialog is a header row plus a scrollable body row, a drilldown's panels stack in the same grid cell so they can cross-fade — none of that is "items in a row," which is the one job flex does well. Reach for flex only when you actually have a one-dimensional run (a top-level nav bar, a horizontal list of chips) — grid handles that case too (grid-auto-flow: column), but flex is the more idiomatic tool there and both are equally valid per the spec.

The mega-menu recipe below is the fullest expression of this rule in the docs; the disclosure and drawer pages apply the same principle at smaller scale (a 0fr → 1fr grid-row for collapse, a two-row grid for a drawer's header + scroll body).

Mega-menu grid recipe ​

A complete panel with a 3-column link grid plus a promo tile that spans two rows — the shape most real mega menus actually need (link columns are rarely all the same height, and a promo tile wants to sit beside them, not below). For the component-API side of this markup (the commandfor/ data-pd-hover-for wiring, hover/open-on-focus, keyboard map) see Nav & mega menu; this recipe is the layout half.

html
<nav aria-label="Main">
  <pd-nav hover open-on-focus>
    <ul class="mm-bar">
      <li class="mm-stop">
        <a href="/collections/skincare" data-pd-hover-for="mm-skincare">Skincare</a>
        <button commandfor="mm-skincare" command="--pd-toggle" aria-label="Skincare menu">▾</button>
        <pd-nav-panel id="mm-skincare" class="mm-panel">
          <div class="mm-col">
            <h3>Serums</h3>
            <a href="/skincare/vitamin-c">Vitamin C</a>
            <a href="/skincare/retinol">Retinol</a>
            <a href="/skincare/niacinamide">Niacinamide</a>
          </div>
          <div class="mm-col">
            <h3>Moisturizers</h3>
            <a href="/skincare/day-cream">Day cream</a>
            <a href="/skincare/night-cream">Night cream</a>
          </div>
          <div class="mm-col">
            <h3>Cleansers</h3>
            <a href="/skincare/foaming">Foaming</a>
            <a href="/skincare/oil">Oil</a>
          </div>
          <a href="/collections/skincare/new" class="mm-promo">
            <img src="/promo-skincare.jpg" alt="" />
            <span>New arrivals →</span>
          </a>
        </pd-nav-panel>
      </li>
      <li class="mm-stop"><a href="/pages/about">About</a></li>
    </ul>
  </pd-nav>
</nav>
css
/* Top-level bar: one-dimensional run, grid-auto-flow: column is fine here
   (flex would be equally valid — this is the exception the spec carves out). */
.mm-bar {
  display: grid;
  grid-auto-flow: column;
  justify-content: start;
  gap: 1.5rem;
  list-style: none;
  margin: 0;
  padding: 0;
}
.mm-stop {
  position: relative; /* anchors the panel below this stop */
  display: grid;
  grid-auto-flow: column;
  align-items: center;
  gap: 0.25rem;
}

/* The panel: genuinely 2D. 3 link columns + a promo tile spanning 2 rows in
   a 4th column — no flex-wrap guesswork, no JS measuring column heights. */
.mm-panel {
  position: absolute;
  inset-inline-start: 0;
  top: 100%;
  z-index: 20;
  display: grid;
  grid-template-columns: repeat(3, minmax(9rem, 1fr)) minmax(12rem, 1fr);
  grid-template-rows: repeat(2, auto);
  gap: 1.5rem 2rem;
  width: max-content;
  padding: 1.5rem;
  background: canvas;
  border: 1px solid color-mix(in oklab, canvasText 15%, transparent);
}
.mm-col {
  display: grid;
  grid-auto-rows: min-content;
  gap: 0.5rem;
  grid-row: 1 / span 2; /* link columns run the panel's full height */
}
.mm-col h3 {
  margin: 0;
  font-size: 0.8rem;
  text-transform: uppercase;
  color: color-mix(in oklab, canvasText 55%, transparent);
}

/* Promo tile: own grid column, spans both rows, image + caption stacked —
   a nested grid, not a nested flex, for the same reason as the parent. */
.mm-promo {
  grid-column: 4;
  grid-row: 1 / span 2;
  display: grid;
  grid-template-rows: 1fr auto;
  overflow: hidden;
  border-radius: 8px;
}
.mm-promo img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

/* Exit animation — see the cookbook below for why data-state, not [hidden],
   is what drives this. */
.mm-panel[data-state='open'] {
  animation: mm-panel-in 160ms ease-out;
}
.mm-panel[data-state='closed'] {
  animation: mm-panel-out 160ms ease-in forwards;
}
@keyframes mm-panel-in {
  from { opacity: 0; transform: translateY(-4px); }
  to   { opacity: 1; transform: translateY(0); }
}
@keyframes mm-panel-out {
  from { opacity: 1; }
  to   { opacity: 0; }
}
@media (prefers-reduced-motion: reduce) {
  .mm-panel { animation: none !important; }
}

Tailwind, same shape:

html
<pd-nav-panel
  id="mm-skincare"
  class="absolute inset-x-0 top-full z-20 grid w-max grid-cols-[repeat(3,minmax(9rem,1fr))_minmax(12rem,1fr)]
         grid-rows-2 gap-x-8 gap-y-6 p-6 bg-white border border-gray-200
         data-[state=open]:[animation:mm-panel-in_160ms_ease-out]
         data-[state=closed]:[animation:mm-panel-out_160ms_ease-in_forwards]
         motion-reduce:[animation:none]"
>
  <div class="row-span-2 grid auto-rows-min gap-2">
    <h3 class="m-0 text-xs uppercase text-gray-500">Serums</h3>
    <a href="/skincare/vitamin-c">Vitamin C</a>
  </div>
  <!-- … two more .mm-col-equivalent divs … -->
  <a href="/collections/skincare/new" class="col-start-4 row-span-2 grid grid-rows-[1fr_auto] overflow-hidden rounded-lg">
    <img src="/promo-skincare.jpg" alt="" class="h-full w-full object-cover" />
    <span>New arrivals →</span>
  </a>
</pd-nav-panel>
css
/* Same caveat as every keyframe-driven Tailwind recipe in these docs:
   declare @keyframes once in your CSS entry, reference by name in the
   arbitrary [animation:…] utilities above. */
@keyframes mm-panel-in {
  from { opacity: 0; transform: translateY(-4px); }
  to   { opacity: 1; transform: translateY(0); }
}
@keyframes mm-panel-out {
  from { opacity: 1; }
  to   { opacity: 0; }
}

Enter/exit animation cookbook ​

The timing model is the same for every disclosure-like element (pd-disclosure, pd-nav-panel, pd-drawer's dialog, pd-drilldown-panel) and it's what makes pure-CSS animation possible with no JS animation config anywhere in the library (SPEC §3):

  • Opening/activation: pending close work is invalidated, component-owned inert is removed, and the surface is revealed before focus can enter it. There is no committed hidden-but-visible frame, so a plain transition cannot animate an entrance on its own — see the @starting-style note below. Author-supplied inert is preserved.
  • Closing/deactivation: data-state flips to "closed"/"inactive" and component-owned inert lands synchronously. The surface remains visually rendered for its exit animation, but its descendants are already absent from the accessibility tree and Tab order. The component then awaits every running CSS animation/transition on it (getAnimations({ subtree: true })). Disclosure/nav panels finish with hidden + pd:closed; a drawer finishes with dialog.close(), focus restoration, and pd:closed; a drilldown panel finishes with hidden and has no close event. That await is why exit animation needs zero JS configuration.

This is why every recipe in these docs keys animation off data-state, never off [hidden] or open directly — data-state is the only attribute that's true for the entire duration of the exit animation.

Exit-only (the common case) ​

css
pd-nav-panel {
  transition: opacity 160ms ease-in;
}
pd-nav-panel[data-state='closed'] {
  opacity: 0;
}

No entrance rule needed: on open, hidden is removed and the panel is already at its resting (opaque) style, so it just appears — instant open, animated close. This is the right default for most disclosure UI (a mega panel, an accordion) where a fast open feels responsive and a slower close feels intentional rather than jarring.

Entrance too, via @starting-style ​

Because opening never has a committed "before" frame, animating an entrance needs @starting-style (Chromium 117+, Firefox 129+, Safari 17.5+) to supply one. Unsupported engines simply skip the block and fall back to an instant open — the exit animation above is unaffected either way, so this is safe progressive enhancement:

css
pd-nav-panel {
  opacity: 1;
  transition: opacity 160ms ease;
}
pd-nav-panel[data-state='closed'] {
  opacity: 0;
}
@starting-style {
  pd-nav-panel[data-state='open'] {
    opacity: 0;
  }
}

Tailwind exposes the same mechanism as the starting: variant: starting:data-[state=open]:opacity-0, layered on top of transition-opacity duration-150 data-[state=closed]:opacity-0.

The <dialog> special case ​

pd-drawer wraps a native <dialog>, which renders in the top layer and paints its ::backdrop as a genuinely separate box the moment showModal() runs — there is no "before" frame for either the dialog or its backdrop to transition from, same root cause as above but now on two boxes at once (::backdrop needs its own @starting-style block). See Drawer → Styling: Vanilla CSS for the full worked recipe, including why the exit transform/opacity rules are keyed on data-state (mirrored onto both pd-drawer and the dialog per SPEC §5.3) rather than the dialog's own [open] attribute, which flips at showModal() time and stays true for the entire duration of the close animation too.

Reduced motion ​

Every recipe in these docs closes with the same guard, and styles/base.css ships an equivalent one for anything you forget to scope yourself:

css
@media (prefers-reduced-motion: reduce) {
  pd-nav-panel,
  pd-disclosure,
  pd-drawer dialog,
  pd-drawer dialog::backdrop,
  pd-drilldown-panel {
    transition: none !important;
    animation: none !important;
  }
}

transition: none still lets the close sequence work correctly — getAnimations() simply returns nothing to await, so the terminal hidden/dialog.close() step lands on the very next microtask instead of after a transition. Reduced motion never breaks the lifecycle; it only removes the animation from it. Tailwind's motion-reduce:transition-none motion-reduce:[animation:none] is the equivalent utility-level guard used throughout the Tailwind recipes in these docs.

Focus rings: keep them on controls, not containers ​

If your theme styles :focus-visible globally (it should — WCAG 2.4.7), add one exclusion:

css
:focus-visible {
  outline: 2px solid var(--accent);
  outline-offset: 3px;
}

/* Containers receive transient script focus on tap-opens/tap-drills;
   the ring belongs on interactive controls, not on the surface itself. */
dialog:focus-visible,
pd-drilldown-panel:focus-visible {
  outline: none;
}

Why: on pointer/tap interactions the drawer and drilldown deliberately focus the container (dialog, destination panel) rather than the first button inside — Safari marks any script-focused element :focus-visible, so focusing a control on tap would paint your focus ring uninvited on every tap-open, tap-drill, and tap-back. Keyboard interactions still focus the first control and get the ring exactly where it belongs. Chromium and Firefox never mark the container, so this rule only matters for Safari — but it's inert everywhere else, so ship it unconditionally. Never suppress :focus-visible on buttons or links themselves.

Your own theme components (quick-view modals, size-guide popovers) can use the same browser signal directly — no library import is needed:

js
const active = document.activeElement
const isKeyboardDriven =
  active instanceof HTMLElement &&
  active.tabIndex >= 0 &&
  active.matches(':focus-visible')

// At interaction time — keyboard activation leaves the invoker :focus-visible,
// a tap/click doesn't (Safari never even focuses tapped buttons):
if (isKeyboardDriven) {
  firstControl.focus()          // ring lands where the keyboard user is
} else {
  container.tabIndex = -1
  container.focus({ preventScroll: true }) // no uninvited Safari ring
}

A common request that has nothing to do with any component's state and needs none: dim every sibling link in a nav bar except the one the pointer is over. This is a decorative affordance, not a disclosure — it's independent of (and safe to combine with) pd-nav's hover attribute, which governs panel opening, not link opacity.

css
nav[aria-label='Main'] a {
  opacity: 1;
  transition: opacity 150ms ease;
}

/* Hovering the nav dims every link... */
nav[aria-label='Main']:hover a {
  opacity: 0.6;
}

/* ...except the one actually under the pointer. */
nav[aria-label='Main'] a:hover {
  opacity: 1;
}

@media (prefers-reduced-motion: reduce) {
  nav[aria-label='Main'] a {
    transition: none;
  }
}

The nav:hover a { opacity: .6 } / nav a:hover { opacity: 1 } pair is the entire trick: the outer rule fires for every link once the pointer enters the nav at all, and the inner, more specific rule (same specificity, later in source order — or just a matching selector on the exact hovered element, which always wins on specificity for :hover chains like this) overrides it back to full opacity for the one link actually being pointed at. No :has(), no JS mouseenter delegation, because the effect only ever needs to react to the pointer's current position, which :hover already tracks natively.

Tailwind, using group:

html
<nav aria-label="Main" class="group/nav">
  <a href="/new" class="opacity-100 transition-opacity duration-150 group-hover/nav:opacity-60 hover:!opacity-100 motion-reduce:transition-none">New</a>
  <a href="/sale" class="opacity-100 transition-opacity duration-150 group-hover/nav:opacity-60 hover:!opacity-100 motion-reduce:transition-none">Sale</a>
</nav>

A named group (group/nav) is needed rather than the bare group class because these links are also likely to sit inside pd-nav's own <li> grouping, which may itself want an unrelated group for its own has-*/hover styling (see the two styling paths above) — named groups let both coexist without colliding. hover:!opacity-100 needs ! (Tailwind's important-marker) only because group-hover/nav:opacity-60 and hover:opacity-100 share the same specificity as utility classes; the ! breaks the tie deterministically instead of relying on source order.

Live demo ​

Real pd-nav wrapping three plain links — no panels, no invokers, just the top-level-stop bar half of the mega-menu anatomy. pd-nav is inert plumbing here (it grants ArrowLeft/ArrowRight/Home/ End movement across the three links per its keyboard map; nothing else in this demo depends on it), which is exactly the point: the hover-fade CSS below asks nothing of the component and works identically whether or not pd-nav is present. Hover the row to see the fade, hover one link to see it stay full-opacity while its siblings dim. Keyboard focus never dims anything — :hover only — so Tab-ing through the links keeps every one fully legible, which is the point: this is a pointer-only affordance layered on top of, never instead of, a fully operable nav.

Next ​

  • Accessibility — the ARIA and focus contract these selectors sit on top of.
  • Component pages (sidebar) — per-element vanilla + Tailwind recipes for every state hook this page introduced.