@kwtv/components 0.3.0 → 0.4.0

package/README.md

@@ -71,6 +71,41 @@ import "@kwtv/components/styles/base.css";
 import "@kwtv/components/styles/controls.css";
 ```
 
+## Cascade layers
+
+Every stylesheet in this package and in `@kwtv/tokens` sits in a cascade
+layer, in one fixed order:
+
+```css
+@layer reset, tokens, base, components, motion, utilities;
+```
+
+| Layer        | Holds                                                           |
+| ------------ | --------------------------------------------------------------- |
+| `reset`      | Empty in the packages. The app's element defaults go here.      |
+| `tokens`     | The token custom properties, in `palette`, `theme` and `scale`. |
+| `base`       | `base.css`: focus ring, touch targets, screen-reader helper.    |
+| `components` | Astro component styles, React island CSS and `controls.css`.    |
+| `motion`     | `motion.css`. Above components, because it adjusts their parts. |
+| `utilities`  | `@kwtv/tokens/utilities.css`.                                   |
+
+Every package stylesheet opens with that order statement. The first one to
+load fixes the order, so it holds whatever order the bundler emits files in.
+
+In the app:
+
+- Put element defaults (`*`, `html`, `body`, `a`, `button`) in
+  `@layer reset { }`. Left unlayered, a bare `a { color }` beats the footer
+  and button link colours.
+- Leave everything else unlayered. Unlayered CSS beats every layer, so a
+  single class overrides any component rule. Do not raise specificity with
+  ids or repeated classes.
+- `!important` flips inside layers: an important declaration in a lower layer
+  wins. The package uses it only to stop animation under reduced motion.
+
+`npm run layers:check` fails when a package stylesheet is missing the order
+statement or has a rule outside its layer.
+
 ## Conventions
 
 - Use the `.astro`, `.tsx` and `.css` extensions shown in these examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kwtv/components",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "UNLICENSED",
   "type": "module",
   "description": "KWTV UI components for Astro, with React islands. Built on the KWTV design tokens.",
@@ -34,6 +34,6 @@
     }
   },
   "dependencies": {
-    "@kwtv/tokens": "^0.3.0"
+    "@kwtv/tokens": "^0.4.0"
   }
 }

package/src/astro/Accordion.astro

@@ -15,11 +15,15 @@ const { class: className, ...rest } = Astro.props;
 </div>
 
 <style>
-  .ui-accordion {
-    display: flex;
-    flex-direction: column;
-    border: 1px solid var(--border);
-    border-radius: var(--radius-lg);
-    overflow: hidden;
+  @layer reset, tokens, base, components, motion, utilities;
+
+  @layer components {
+    .ui-accordion {
+      display: flex;
+      flex-direction: column;
+      border: 1px solid var(--border);
+      border-radius: var(--radius-lg);
+      overflow: hidden;
+    }
   }
 </style>

package/src/astro/AccordionItem.astro

@@ -31,53 +31,57 @@ const { summary, open = false, class: className, ...rest } = Astro.props;
 </details>
 
 <style>
-  .ui-accordion__item + .ui-accordion__item {
-    border-top: 1px solid var(--border);
-  }
-
-  .ui-accordion__sum {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: var(--space-3);
-    min-height: 44px;
-    padding: var(--space-2) var(--space-4);
-    font-size: var(--text-sm);
-    font-weight: var(--weight-medium);
-    color: var(--text);
-    cursor: pointer;
-    list-style: none;
-  }
-  .ui-accordion__sum::-webkit-details-marker {
-    display: none;
-  }
-  .ui-accordion__sum:hover {
-    background: var(--surface-hover);
-  }
-  .ui-accordion__sum:focus-visible {
-    outline: 2px solid var(--focus);
-    outline-offset: -2px;
-  }
+  @layer reset, tokens, base, components, motion, utilities;
 
-  .ui-accordion__chev {
-    display: inline-flex;
-    color: var(--text-muted);
-    transition: transform var(--duration-fast) var(--ease-standard);
-  }
-  .ui-accordion__item[open] .ui-accordion__chev {
-    transform: rotate(180deg);
-  }
+  @layer components {
+    .ui-accordion__item + .ui-accordion__item {
+      border-top: 1px solid var(--border);
+    }
 
-  .ui-accordion__body {
-    padding: 0 var(--space-4) var(--space-4);
-    font-size: var(--text-sm);
-    line-height: var(--leading-sm);
-    color: var(--text-muted);
-  }
+    .ui-accordion__sum {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--space-3);
+      min-height: 44px;
+      padding: var(--space-2) var(--space-4);
+      font-size: var(--text-sm);
+      font-weight: var(--weight-medium);
+      color: var(--text);
+      cursor: pointer;
+      list-style: none;
+    }
+    .ui-accordion__sum::-webkit-details-marker {
+      display: none;
+    }
+    .ui-accordion__sum:hover {
+      background: var(--surface-hover);
+    }
+    .ui-accordion__sum:focus-visible {
+      outline: 2px solid var(--focus);
+      outline-offset: -2px;
+    }
 
-  @media (prefers-reduced-motion: reduce) {
     .ui-accordion__chev {
-      transition: none;
+      display: inline-flex;
+      color: var(--text-muted);
+      transition: transform var(--duration-fast) var(--ease-standard);
+    }
+    .ui-accordion__item[open] .ui-accordion__chev {
+      transform: rotate(180deg);
+    }
+
+    .ui-accordion__body {
+      padding: 0 var(--space-4) var(--space-4);
+      font-size: var(--text-sm);
+      line-height: var(--leading-sm);
+      color: var(--text-muted);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .ui-accordion__chev {
+        transition: none;
+      }
     }
   }
 </style>

package/src/astro/ActiveFilterTags.astro

@@ -44,31 +44,35 @@ const classes = ["ui-filtertags", className].filter(Boolean).join(" ");
 </div>
 
 <style>
-  .ui-filtertags {
-    display: flex;
-    flex-wrap: wrap;
-    align-items: center;
-    gap: var(--space-2);
-  }
+  @layer reset, tokens, base, components, motion, utilities;
 
-  .ui-filtertags__clear {
-    padding: var(--space-1-5) var(--space-2);
-    background: transparent;
-    border: 0;
-    border-radius: var(--radius-sm);
-    font-family: var(--font-sans);
-    font-size: var(--text-xs);
-    font-weight: var(--weight-semibold);
-    color: var(--link);
-    cursor: pointer;
-  }
-  .ui-filtertags__clear:hover {
-    background: var(--surface-hover);
-    color: var(--link-hover);
-  }
-  .ui-filtertags__clear:focus-visible {
-    outline: 2px solid var(--focus);
-    outline-offset: 2px;
-    box-shadow: 0 0 0 4px var(--focus-outer);
+  @layer components {
+    .ui-filtertags {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--space-2);
+    }
+
+    .ui-filtertags__clear {
+      padding: var(--space-1-5) var(--space-2);
+      background: transparent;
+      border: 0;
+      border-radius: var(--radius-sm);
+      font-family: var(--font-sans);
+      font-size: var(--text-xs);
+      font-weight: var(--weight-semibold);
+      color: var(--link);
+      cursor: pointer;
+    }
+    .ui-filtertags__clear:hover {
+      background: var(--surface-hover);
+      color: var(--link-hover);
+    }
+    .ui-filtertags__clear:focus-visible {
+      outline: 2px solid var(--focus);
+      outline-offset: 2px;
+      box-shadow: 0 0 0 4px var(--focus-outer);
+    }
   }
 </style>

package/src/astro/Alert.astro

@@ -41,53 +41,57 @@ const classes = ["ui-alert", `ui-alert--${tone}`, className]
 </div>
 
 <style>
-  .ui-alert {
-    display: flex;
-    align-items: flex-start;
-    gap: var(--space-2-5, 0.625rem);
-    padding: var(--space-3) var(--space-4);
-    border-left: 3px solid currentColor;
-    border-radius: var(--radius-md);
-    font-family: var(--font-sans);
-    font-size: var(--text-sm);
-    line-height: var(--leading-sm);
-  }
+  @layer reset, tokens, base, components, motion, utilities;
 
-  .ui-alert__icon {
-    display: inline-flex;
-    flex-shrink: 0;
-    margin-top: 1px;
-  }
+  @layer components {
+    .ui-alert {
+      display: flex;
+      align-items: flex-start;
+      gap: var(--space-2-5, 0.625rem);
+      padding: var(--space-3) var(--space-4);
+      border-left: 3px solid currentColor;
+      border-radius: var(--radius-md);
+      font-family: var(--font-sans);
+      font-size: var(--text-sm);
+      line-height: var(--leading-sm);
+    }
 
-  /* Body keeps full strength; the left rule carries the tone. */
-  .ui-alert__body {
-    color: var(--text);
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-1);
-  }
+    .ui-alert__icon {
+      display: inline-flex;
+      flex-shrink: 0;
+      margin-top: 1px;
+    }
 
-  .ui-alert__title {
-    font-weight: var(--weight-semibold);
-  }
+    /* Body keeps full strength; the left rule carries the tone. */
+    .ui-alert__body {
+      color: var(--text);
+      display: flex;
+      flex-direction: column;
+      gap: var(--space-1);
+    }
 
-  .ui-alert--info {
-    background: var(--surface-accent);
-    color: var(--surface-accent-fg, var(--primary));
-  }
+    .ui-alert__title {
+      font-weight: var(--weight-semibold);
+    }
 
-  .ui-alert--success {
-    background: var(--success-bg);
-    color: var(--success);
-  }
+    .ui-alert--info {
+      background: var(--surface-accent);
+      color: var(--surface-accent-fg, var(--primary));
+    }
 
-  .ui-alert--warning {
-    background: var(--warning-bg);
-    color: var(--warning);
-  }
+    .ui-alert--success {
+      background: var(--success-bg);
+      color: var(--success);
+    }
+
+    .ui-alert--warning {
+      background: var(--warning-bg);
+      color: var(--warning);
+    }
 
-  .ui-alert--danger {
-    background: var(--danger-bg);
-    color: var(--danger);
+    .ui-alert--danger {
+      background: var(--danger-bg);
+      color: var(--danger);
+    }
   }
 </style>

package/src/astro/Badge.astro

@@ -58,81 +58,85 @@ const classes = [
 </span>
 
 <style>
-  .ui-badge {
-    display: inline-flex;
-    align-items: center;
-    gap: var(--space-1-5);
-    min-height: 24px;
-    padding: 0 var(--space-2);
-    border: 1px solid transparent;
-    border-radius: var(--radius-full);
-    font-family: var(--font-sans);
-    font-size: var(--text-xs);
-    font-weight: var(--weight-medium);
-    line-height: 1;
-    white-space: nowrap;
-  }
-
-  .ui-badge__icon {
-    display: inline-flex;
-    flex-shrink: 0;
-  }
-
-  .ui-badge--neutral {
-    background: var(--surface-accent);
-    color: var(--surface-accent-fg, var(--text));
-  }
-
-  .ui-badge--success {
-    background: var(--success-bg);
-    color: var(--success);
-  }
-
-  .ui-badge--warning {
-    background: var(--warning-bg);
-    color: var(--warning);
-  }
-
-  .ui-badge--danger {
-    background: var(--danger-bg);
-    color: var(--danger);
-  }
-
-  /* Outline keeps the strong border and full-strength text, so it reads
-     without relying on a fill. */
-  .ui-badge--outline {
-    background: transparent;
-    border: 1px solid var(--border-strong);
-    color: var(--text);
-  }
-
-  .ui-badge--removable {
-    padding-right: var(--space-1);
-  }
-
-  /* Small × target grows with padding plus an equal negative margin, so the
-     hit area grows without moving the layout. */
-  .ui-badge__x {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    padding: var(--space-2);
-    margin: calc(-1 * var(--space-2));
-    margin-left: 0;
-    background: transparent;
-    border: 0;
-    border-radius: var(--radius-sm);
-    color: inherit;
-    cursor: pointer;
-  }
-
-  .ui-badge__x:hover {
-    color: var(--danger);
-  }
-
-  .ui-badge__x:focus-visible {
-    outline: 2px solid var(--focus);
-    outline-offset: 2px;
-    box-shadow: 0 0 0 4px var(--focus-outer);
+  @layer reset, tokens, base, components, motion, utilities;
+
+  @layer components {
+    .ui-badge {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--space-1-5);
+      min-height: 24px;
+      padding: 0 var(--space-2);
+      border: 1px solid transparent;
+      border-radius: var(--radius-full);
+      font-family: var(--font-sans);
+      font-size: var(--text-xs);
+      font-weight: var(--weight-medium);
+      line-height: 1;
+      white-space: nowrap;
+    }
+
+    .ui-badge__icon {
+      display: inline-flex;
+      flex-shrink: 0;
+    }
+
+    .ui-badge--neutral {
+      background: var(--surface-accent);
+      color: var(--surface-accent-fg, var(--text));
+    }
+
+    .ui-badge--success {
+      background: var(--success-bg);
+      color: var(--success);
+    }
+
+    .ui-badge--warning {
+      background: var(--warning-bg);
+      color: var(--warning);
+    }
+
+    .ui-badge--danger {
+      background: var(--danger-bg);
+      color: var(--danger);
+    }
+
+    /* Outline keeps the strong border and full-strength text, so it reads */
+    /* without relying on a fill. */
+    .ui-badge--outline {
+      background: transparent;
+      border: 1px solid var(--border-strong);
+      color: var(--text);
+    }
+
+    .ui-badge--removable {
+      padding-right: var(--space-1);
+    }
+
+    /* Small × target grows with padding plus an equal negative margin, so the */
+    /* hit area grows without moving the layout. */
+    .ui-badge__x {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: var(--space-2);
+      margin: calc(-1 * var(--space-2));
+      margin-left: 0;
+      background: transparent;
+      border: 0;
+      border-radius: var(--radius-sm);
+      color: inherit;
+      cursor: pointer;
+    }
+
+    .ui-badge__x:hover {
+      color: var(--danger);
+    }
+
+    .ui-badge__x:focus-visible {
+      outline: 2px solid var(--focus);
+      outline-offset: 2px;
+      box-shadow: 0 0 0 4px var(--focus-outer);
+    }
   }
 </style>