@ropav/styles 0.5.0 → 0.6.0

package/README.md

@@ -112,6 +112,11 @@ component that publishes it as an attribute.
 
 `components/button.css` is the densest example of both — read it before writing a new component file.
 
+**Every `ropav` component takes a `class` prop**, merged through its `tv()` recipe rather than
+concatenated, so a utility that conflicts with one the recipe already carries replaces it. That is
+the first thing to reach for. It cannot reach a part drawn in `::before`/`::after`, and it flattens
+every state of whatever property it sets — see [State colors](#state-colors) for the way round both.
+
 ## Theming
 
 Two independent axes. `data-theme` picks the palette, a `light`/`dark` class picks the appearance:
@@ -203,6 +208,80 @@ scrollbar set, and shadows.
 stale the moment a token moves. `themes/shared/theme.css` holds what is derived from those tokens: the
 `--radius-xs` … `--radius-4xl` scale and the easing curves.
 
+### State colors
+
+A component's own properties are the third tier, declared on its block and private to its file —
+`--button-bg`, `--switch-control-bg-checked-hover`, `--sidebar-rail-line`. The convention:
+
+> **A color a state rule paints goes through a custom property — where more than one state paints
+> that property.**
+
+That is what makes one state retunable on its own. A color written straight into the rule is not:
+the resting and the lit value are the same property on the same element, so the one declaration a
+caller writes to change either beats every state rule at once — and a utility beats them all
+whatever their specificity, `utilities` being a later layer than `components`. The only way left is
+to restate the whole state set behind `:not()`, which drifts silently the day a state is added.
+
+So a caller sets the property instead, and the states that read the others are left standing:
+
+```html
+<!-- No line at rest; it still flares on hover and while dragging. -->
+<SidebarRoot class="[--sidebar-rail-line:transparent]">
+```
+
+The qualifier is what keeps this from becoming surface for its own sake. Where exactly one state
+paints a property, a caller can name that state from the call site — `hover:bg-*`, `focus-visible:outline-*` —
+and there is no other state for it to flatten, so no property is minted. It is the second state
+painting the same thing that makes the call site unable to tell them apart.
+
+Defaults chain, so retuning one carries the states below it unless they are set too —
+`--sidebar-rail-line-dragging` follows `--sidebar-rail-line-hover`, the way `--button-bg-pressed`
+follows `--button-bg-hover`. Read `components/button.css` for the shape and
+`components/sidebar.css` for a part painted on a pseudo-element, which a class cannot reach at all.
+
+Two limits. The properties are per component and resolve to the tokens above, so a palette change
+belongs in a theme rather than here. And Forced Colors Mode is not covered: those blocks paint the
+system keywords, which are the only colors exempt from the override and not a component's to
+retune — `[--sidebar-rail-line:transparent]` leaves the line drawn under High Contrast, on purpose.
+
+`state-colors.test.ts` in the `ropav` package reads every component file and fails on a state color
+that does not go through a property. Its ledger of exceptions is currently empty, so an entry
+appearing there is debt to pay down rather than a licence to add more.
+
+### Translucent surfaces
+
+A `surface--transparent` paints nothing of its own, and so does a surface a caller has thinned to
+let something through — a blurred header, a panel over an image, a window whose material the OS
+draws. What sits on one of those has no way to know what is behind it, and that splits the palette
+in two.
+
+**Safe on anything: the tokens that are an alpha.** `--state-layer` is what a state paints, and
+`--separator` and `--border` are the lines — each an alpha of `--surface-foreground` rather than a
+neutral of its own. An alpha darkens or lightens whatever it lands on, so it holds its contrast
+against a fill it was never tuned for: another surface, the far half of the theme, or a photograph.
+The `-soft` family and `--scrollbar-thumb` are alphas too, which is why a selection is
+`--accent-soft` wherever the library marks one.
+
+**Not safe: the fills.** `--default`, `--accent`, the status colors, `--surface` and its secondary
+and tertiary steps are opaque, and they are meant to be — a badge you can read the page through is a
+broken badge. They assume a background because they *are* one. Use them to fill a box, never to mark
+a state on a box that is already transparent.
+
+`--surface-hover` sits on the fill side of that line despite the name: it is a surface that has been
+tinted and stays opaque, for a component opaque at rest whose hover must stay that way.
+`--state-layer` is the one for a component transparent at rest. Reaching for the wrong one fails
+quietly — a translucent hover on an opaque tag shows the page through it, and a flat neutral on a
+transparent row vanishes the moment the fill behind it matches.
+
+The line between the two is what a color is for, not what it looks like. `--default` is a fine grey
+until it is asked to be a state layer: then it is a fixed lightness laid on an unknown one, and the
+day those two match it is gone with nothing to fail but the eye.
+
+**Contrast on a translucent surface is the app's to guarantee.** `contrast.browser.test.ts` holds
+the floor for text on the fills, where both sides are known. Once the background is whatever happens
+to be behind the window, ropav cannot see it and does not claim to — an app that thins a surface
+owns the legibility of what it puts there.
+
 ### Reduced motion
 
 `data-reduce-motion="true"` on any ancestor forces animations off, `"false"` forces them on regardless

package/dist/components/accordion.css

@@ -59,10 +59,6 @@
   /* Base Styles */
   @apply flex flex-1 items-center justify-between px-4 py-4 text-start text-sm font-medium no-highlight;
 
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition:
     opacity 150ms var(--ease-out),
     box-shadow 150ms var(--ease-out);
@@ -98,10 +94,6 @@
   height: var(--disclosure-panel-height);
   overflow: clip;
 
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition:
     height 200ms var(--ease-out-quad),
     opacity 200ms var(--ease-out);
@@ -129,7 +121,7 @@
     @media (hover: hover) {
       &:hover:not([aria-expanded="true"]),
       &[data-hovered="true"]:not([aria-expanded="true"]) {
-        @apply bg-default;
+        @apply bg-state-layer;
       }
     }
   }

package/dist/components/alert-dialog.css

@@ -10,10 +10,6 @@
   @apply inline-block;
   @apply cursor-(--cursor-interactive);
 
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition:
     transform 250ms var(--ease-out-quart),
     background-color 150ms var(--ease-smooth),
@@ -57,10 +53,6 @@
     @apply animate-out duration-100 ease-out fade-out-0;
   }
 
-  /**
-   * Reduce Animation
-   * CRITICAL: motion-reduce must be AFTER animate for correct override specificity
-   */
   &[data-exiting="true"],
   &[data-entering="true"] {
     @apply will-change-[opacity];
@@ -126,10 +118,6 @@
     @apply animate-out duration-100 ease-out-quad fade-out-0 zoom-out-95;
   }
 
-  /**
-   * Reduce Animation
-   * CRITICAL: motion-reduce must be AFTER animate for correct override specificity
-   */
   &[data-exiting="true"],
   &[data-entering="true"] {
     @apply will-change-[opacity,transform];

package/dist/components/autocomplete.css

@@ -4,7 +4,14 @@
 }
 
 .autocomplete__trigger {
-  @apply relative isolate inline-flex min-h-9 rounded-field border bg-field px-3 field-line-md text-field-foreground shadow-field outline-none select-none no-highlight;
+  @apply relative isolate inline-flex min-h-9 rounded-field border px-3 field-line-md text-field-foreground shadow-field outline-none select-none no-highlight;
+
+  /* The fill, per state. The `--secondary` variant re-points these and declares nothing else. */
+  --autocomplete-trigger-bg: var(--field-background, var(--default));
+  --autocomplete-trigger-bg-hover: var(--field-hover);
+  --autocomplete-trigger-bg-focus: var(--field-focus);
+
+  background-color: var(--autocomplete-trigger-bg);
 
   /* Forced Colors Mode flattens the fill onto the page and strips the shadow, leaving a control
    * with nothing to say it is one. `ButtonBorder` is the keyword the platform uses for a
@@ -14,10 +21,6 @@
     outline-offset: -1px;
   }
 
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition:
     background-color 150ms var(--ease-smooth),
     border-color 150ms var(--ease-smooth),
@@ -39,7 +42,7 @@
   @media (hover: hover) {
     &:hover:not(:has(.autocomplete__clear-button:hover)),
     &[data-hovered="true"]:not(:has(.autocomplete__clear-button:hover)) {
-      @apply bg-field-hover;
+      background-color: var(--autocomplete-trigger-bg-hover);
       border-color: var(--field-border-hover);
     }
   }
@@ -49,7 +52,7 @@
   &[data-focus-visible="true"] {
     @apply status-focused;
     border-color: var(--field-border-focus);
-    background-color: var(--field-focus);
+    background-color: var(--autocomplete-trigger-bg-focus);
   }
 
   /* Focus state */
@@ -61,7 +64,7 @@
   .autocomplete[data-invalid="true"] &,
   .autocomplete[aria-invalid="true"] & {
     @apply status-invalid-field;
-    background-color: var(--field-focus);
+    background-color: var(--autocomplete-trigger-bg-focus);
   }
 
   /* Disabled state */
@@ -79,40 +82,22 @@
 
 .autocomplete--secondary .autocomplete__trigger {
   @apply shadow-none;
-  background-color: var(--autocomplete-trigger-bg);
 
   --autocomplete-trigger-bg: var(--default);
   --autocomplete-trigger-bg-hover: var(--default-hover);
   --autocomplete-trigger-bg-focus: var(--default);
-
-  /* Exclude when clear button is hovered to prevent double hover effect */
-  @media (hover: hover) {
-    &:hover:not(:has(.autocomplete__clear-button:hover)),
-    &[data-hovered="true"]:not(:has(.autocomplete__clear-button:hover)) {
-      background-color: var(--autocomplete-trigger-bg-hover);
-    }
-  }
-
-  &:focus-visible:not(:focus),
-  &[data-focus-visible="true"] {
-    background-color: var(--autocomplete-trigger-bg-focus);
-  }
-
-  &:focus,
-  &[data-focus="true"] {
-  }
-
-  .autocomplete[data-invalid="true"] &,
-  .autocomplete[aria-invalid="true"] & {
-    background-color: var(--autocomplete-trigger-bg-focus);
-  }
 }
 
 .autocomplete__value {
-  @apply flex-1 text-start wrap-break-word text-current;
+  @apply flex-1 text-start wrap-break-word;
+
+  --autocomplete-value-fg: currentcolor;
+  --autocomplete-value-fg-placeholder: var(--field-placeholder, var(--muted));
+
+  color: var(--autocomplete-value-fg);
 
   &[data-placeholder="true"] {
-    @apply text-field-placeholder;
+    color: var(--autocomplete-value-fg-placeholder);
   }
 
   /* Removes the list-box-item indicator element from the autocomplete value*/
@@ -252,7 +237,12 @@
 /* Clear Button styles */
 .autocomplete__clear-button {
   @apply relative isolate inline-flex h-6 w-6 shrink-0 origin-center items-center justify-center rounded-xl p-1 text-muted select-none no-highlight;
-  @apply me-0 size-5 shrink-0 self-center bg-transparent;
+  @apply me-0 size-5 shrink-0 self-center;
+
+  --autocomplete-clear-button-bg: transparent;
+  --autocomplete-clear-button-bg-hover: var(--default-hover);
+
+  background-color: var(--autocomplete-clear-button-bg);
 
   /* Cursor */
   cursor: var(--cursor-interactive);
@@ -280,7 +270,7 @@
   @media (hover: hover) {
     &:hover,
     &[data-hovered="true"] {
-      @apply bg-default-hover;
+      background-color: var(--autocomplete-clear-button-bg-hover);
     }
   }
 

package/dist/components/breadcrumbs.css

@@ -4,7 +4,12 @@
 
   /* Breadcrumb link */
   .breadcrumbs__link {
-    @apply relative px-0.5 text-sm leading-5 font-medium text-muted no-underline opacity-100;
+    @apply relative px-0.5 text-sm leading-5 font-medium no-underline opacity-100;
+
+    --breadcrumbs-link-fg: var(--muted);
+    --breadcrumbs-link-fg-current: var(--link);
+
+    color: var(--breadcrumbs-link-fg);
 
     &:hover,
     &[data-hovered="true"] {
@@ -12,7 +17,9 @@
     }
 
     &[data-current="true"] {
-      @apply text-link opacity-100;
+      @apply opacity-100;
+
+      color: var(--breadcrumbs-link-fg-current);
     }
   }
 

package/dist/components/button-group.css

@@ -75,10 +75,6 @@
   position: absolute;
   pointer-events: none;
 
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition: opacity 150ms var(--ease-smooth);
   @apply motion-reduce:transition-none;
 

package/dist/components/button.css

@@ -4,10 +4,6 @@
 .button {
   @apply relative isolate inline-flex h-9 w-fit origin-center items-center justify-center gap-2 rounded-component px-4 text-sm font-medium whitespace-nowrap outline-none select-none no-highlight;
 
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition:
     transform 250ms var(--ease-smooth),
     background-color 100ms var(--ease-out),
@@ -130,14 +126,14 @@
 .button--ghost,
 .button--outline {
   --button-bg: transparent;
-  --button-bg-hover: var(--default);
-  --button-bg-pressed: var(--default);
+  --button-bg-hover: var(--state-layer);
+  --button-bg-pressed: var(--state-layer);
   --button-fg: var(--default-foreground);
 }
 
 .button--outline {
   @apply border border-border;
-  --button-bg-hover: color-mix(in srgb, var(--default) 60%, transparent);
+  --button-bg-hover: color-mix(in oklab, var(--state-layer) 60%, transparent);
 }
 
 .button--danger {

package/dist/components/calendar-year-picker.css

@@ -119,10 +119,19 @@
   @apply relative inline-flex h-8 items-center justify-center rounded-component px-2.5 text-sm font-medium outline-none select-none no-highlight;
   touch-action: manipulation;
 
-  /**
-   * Transitions – same as .tag
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
+  /* The fill and label, per state — selected and hovered land together on the current year. */
+  --calendar-year-picker-year-cell-bg: transparent;
+  --calendar-year-picker-year-cell-bg-hover: var(--state-layer);
+  --calendar-year-picker-year-cell-bg-selected: var(--accent);
+  --calendar-year-picker-year-cell-bg-selected-hover: var(--accent-hover);
+  --calendar-year-picker-year-cell-fg: currentcolor;
+  --calendar-year-picker-year-cell-fg-hover: var(--default-foreground);
+  --calendar-year-picker-year-cell-fg-selected: var(--accent-foreground);
+
+  background-color: var(--calendar-year-picker-year-cell-bg);
+  color: var(--calendar-year-picker-year-cell-fg);
+
+  /* Same as `.tag`. */
   transition:
     color 100ms var(--ease-smooth),
     scale 100ms var(--ease-smooth),
@@ -136,19 +145,22 @@
   /* Hover state (when not selected) – only on devices that support hover */
   @media (hover: hover) and (pointer: fine) {
     &:is(:hover, [data-hovered="true"]):not([data-selected="true"]) {
-      @apply bg-default text-default-foreground;
+      background-color: var(--calendar-year-picker-year-cell-bg-hover);
+      color: var(--calendar-year-picker-year-cell-fg-hover);
     }
   }
 
   /* Selected state (current year) – same as .tag[data-selected] */
   &[data-selected="true"],
   &[aria-selected="true"] {
-    @apply bg-accent text-accent-foreground;
+    background-color: var(--calendar-year-picker-year-cell-bg-selected);
+    color: var(--calendar-year-picker-year-cell-fg-selected);
+
     @apply forced-selected;
 
     @media (hover: hover) and (pointer: fine) {
       &:is(:hover, [data-hovered="true"]) {
-        @apply bg-accent-hover;
+        background-color: var(--calendar-year-picker-year-cell-bg-selected-hover);
       }
     }
   }

package/dist/components/calendar.css

@@ -80,14 +80,12 @@
 }
 
 .calendar__nav-button {
-  @apply flex size-6 items-center justify-center rounded-2xl text-accent-soft-foreground;
+  @apply flex size-6 items-center justify-center text-accent-soft-foreground;
+
+  border-radius: min(32px, var(--component-radius));
 
   will-change: scale;
 
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition:
     transform 250ms var(--ease-out),
     background-color 100ms var(--ease-out),
@@ -101,7 +99,7 @@
   @media (hover: hover) {
     &:hover,
     &[data-hovered="true"] {
-      @apply bg-default text-accent-soft-foreground;
+      @apply bg-state-layer;
     }
   }
 
@@ -183,13 +181,30 @@
  * -------------------------------------------------------------------------- */
 .calendar__cell {
   /* Cell (td) wrapper styles - margins now work with grid layout */
-  @apply relative flex aspect-square size-full items-center justify-center rounded-3xl text-center text-sm font-medium outline-none no-highlight;
+  @apply relative flex aspect-square size-full items-center justify-center text-center text-sm font-medium outline-none no-highlight;
+
+  border-radius: min(32px, var(--component-radius));
+
+  /* Eight states repaint a day, several of them in pairs — today and hovered, selected and
+   * pressed, selected and outside the month. One declaration cannot tell them apart, so each
+   * reads its own. */
+  --calendar-cell-bg: transparent;
+  --calendar-cell-bg-hover: var(--state-layer);
+  --calendar-cell-bg-pressed: var(--calendar-cell-bg-hover);
+  --calendar-cell-bg-today: var(--accent-soft);
+  --calendar-cell-bg-today-hover: var(--accent-soft-hover);
+  --calendar-cell-bg-selected: var(--accent);
+  --calendar-cell-bg-selected-pressed: var(--accent-hover);
+  --calendar-cell-bg-selected-outside-month: var(--state-layer);
+  --calendar-cell-fg: currentcolor;
+  --calendar-cell-fg-today: var(--accent-soft-foreground);
+  --calendar-cell-fg-selected: var(--accent-foreground);
+  --calendar-cell-fg-outside-month: var(--muted);
+
+  background-color: var(--calendar-cell-bg);
+  color: var(--calendar-cell-fg);
 
   will-change: scale;
-  /**
-   * Transitions
-   * CRITICAL: motion-reduce must be AFTER transition for correct override specificity
-   */
   transition:
     transform 250ms var(--ease-out),
     box-shadow 100ms var(--ease-out);
@@ -205,7 +220,8 @@
 
   /* Today indicator */
   &[data-today="true"] {
-    @apply bg-accent-soft text-accent-soft-foreground;
+    background-color: var(--calendar-cell-bg-today);
+    color: var(--calendar-cell-fg-today);
 
     /* A tinted background is all that marks today, and forced colors flattens it onto the page.
      * An edge rather than a fill, so today still reads as itself once it is also selected. */
@@ -217,25 +233,27 @@
     @media (hover: hover) {
       &:hover:not([data-selected="true"]),
       &[data-hovered="true"]:not([data-selected="true"]) {
-        @apply bg-accent-soft-hover;
+        background-color: var(--calendar-cell-bg-today-hover);
       }
     }
   }
 
   /* Selected state */
   &[data-selected="true"] {
-    @apply bg-accent text-accent-foreground;
+    background-color: var(--calendar-cell-bg-selected);
+    color: var(--calendar-cell-fg-selected);
+
     @apply forced-selected;
   }
 
   /* Pressed state */
   &:active,
   &[data-pressed="true"] {
-    @apply bg-default;
+    background-color: var(--calendar-cell-bg-pressed);
     transform: scale(0.95);
 
     &[data-selected="true"] {
-      @apply bg-accent-hover;
+      background-color: var(--calendar-cell-bg-selected-pressed);
     }
   }
 
@@ -243,17 +261,19 @@
   @media (hover: hover) {
     &:hover:not([data-selected="true"]),
     &[data-hovered="true"]:not([data-selected="true"]) {
-      @apply bg-default;
+      background-color: var(--calendar-cell-bg-hover);
     }
   }
 
   /* Outside month (previous/next month days) */
   &[data-outside-month="true"] {
-    @apply text-muted opacity-50;
+    @apply opacity-50;
+
+    color: var(--calendar-cell-fg-outside-month);
   }
 
   &[data-selected="true"][data-outside-month="true"] {
-    @apply bg-default;
+    background-color: var(--calendar-cell-bg-selected-outside-month);
   }
 
   /* Unavailable dates */
@@ -272,10 +292,15 @@
 
 /* Cell indicator - small dot at bottom center of cell */
 .calendar__cell-indicator {
-  @apply absolute bottom-1 left-1/2 size-[3px] -translate-x-1/2 rounded-xs bg-muted;
+  @apply absolute bottom-1 left-1/2 size-[3px] -translate-x-1/2 rounded-xs;
+
+  --calendar-cell-indicator-bg: var(--muted);
+  --calendar-cell-indicator-bg-selected: var(--accent-foreground);
+
+  background-color: var(--calendar-cell-indicator-bg);
 
   /* Indicator color changes when cell is selected */
   [data-selected="true"] > & {
-    @apply bg-accent-foreground;
+    background-color: var(--calendar-cell-indicator-bg-selected);
   }
 }