gbs-add-block 2.0.3 → 2.1.0

package/.gbs/skills/gbs-components/references/styling.md

@@ -113,18 +113,25 @@ exist is silently ignored, so check the list.
 Classes are joined with `cx` from `shared/core/cx.ts`, which drops falsy values
 — a conditional that evaluates to `undefined` contributes nothing.
 
-## 4. Tailwind
+## 4. Cascade layers and Tailwind
 
-Every `styles.css` declares:
+Every `styles.css` ships its rules in one layer and declares nothing else:
 
 ```css
-@layer theme, base, components, utilities;
-@layer components { /* the component's rules */ }
+@layer gbs { /* the component's rules */ }
 ```
 
-Component rules live in the `components` layer, so **Tailwind utilities passed
-through `className` / `classNames` win** without `!important`. That is the
-supported way to adjust spacing, typography and layout.
+Where `gbs` sits is the app's call. Declare the order once in the global CSS;
+anything in a later layer beats the components:
+
+```css
+@layer reset, gbs, app, utilities;
+```
+
+With Tailwind v4, naming `gbs` before `utilities` means **a utility passed
+through `className` / `classNames` wins** without `!important`. Tailwind v3
+needs no line — it emits utilities unlayered, which already outrank a layer.
+A project with no CSS framework needs no line either.
 
 ```tsx
 <Button className="w-full sm:w-auto" classNames={{ content: "gap-3" }}>Save</Button>
@@ -134,7 +141,25 @@ Do not use `!important`, and do not write selectors against internal class names
 (`.bt-root`, `.dg-cell`) in app CSS — they are implementation detail. Use the
 variables or the slots.
 
-## 5. State attributes
+## 5. Unlayered resets (Bootstrap, Normalize)
+
+Any stylesheet that ships **unlayered** beats every layered rule regardless of
+specificity — the cascade settles layers before specificity. So Bootstrap's
+Reboot (`button { border-radius: 0 }`, `button, input, textarea { font-size:
+inherit }`) overrides our classes, and import order does not help.
+
+Fix it in the project's global CSS by giving the reset its own layer, named
+before `gbs`:
+
+```css
+@layer bootstrap, gbs, app, utilities;
+@import url("bootstrap/dist/css/bootstrap.min.css") layer(bootstrap);
+```
+
+Only components whose root is a native form element are affected (Button,
+Textarea). Class names never collide — ours are two-letter prefixed.
+
+## 6. State attributes
 
 Components expose their state as `data-*` attributes, so you can style states
 without tracking them in React.
@@ -155,7 +180,7 @@ without tracking them in React.
 .cb-option[data-active] { outline: 2px solid var(--gbs-focus); }
 ```
 
-## 6. Dark mode
+## 7. Dark mode
 
 Colours are `light-dark()` pairs driven by the page's `color-scheme`, so the
 default is whatever the device prefers. To pin it, set `color-scheme` — the
@@ -174,7 +199,7 @@ Do not maintain a second palette for dark mode. Override the `--gbs-*` variables
 with `light-dark()` pairs, or set them inside your own `[data-theme="dark"]`
 block, and every component follows.
 
-## 7. Right-to-left
+## 8. Right-to-left
 
 The components use logical properties and read `dir` from the document, so RTL
 works without configuration. Arrow keys in Menu, Switch and Tabs mirror

package/README.md

@@ -1,4 +1,4 @@
-# GBS Building Blocks 2.0 (v2.0.3)
+# GBS Building Blocks 2.0 (v2.1.0)
 
 Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
 
@@ -33,13 +33,28 @@ Pick a subset with `--for claude,codex`, or `--for none` for just `.gbs/`.
 Commit the result so everyone's agent picks it up. Re-run to update; a file you
 have edited is never replaced without `--force`.
 
-## What's New 🎉 (Ver 2.0.3)
+## What's New 🎉 (Ver 2.1.0)
 
-- Agent skill: stylesheets are now documented as a single import in the
-  project's global CSS. The previous wording showed the stylesheet import
-  beside the component import, which led coding agents to repeat it in every
-  component file they wrote — making CSS order depend on module import order,
-  and arriving late on lazy-loaded routes.
+**The application now owns CSS cascade order.** Component rules moved out of the
+`components` layer into a layer of their own, `gbs`, and the stylesheets no
+longer declare a global layer order.
+
+Previously every `styles.css` opened with
+`@layer theme, base, components, utilities;` — a leaf file asserting the order
+of the whole document. Whichever stylesheet the bundler emitted first silently
+won that argument. It also meant a Tailwind v3 build failed outright, and
+Bootstrap's Reboot could not be put in front of the components.
+
+- Tailwind **v3** projects now build. Utilities override components there too,
+  with no setup.
+- Tailwind **v4** projects add one line to their global CSS:
+  `@layer gbs, utilities;` — **without it, utilities no longer override
+  component styles.** This is the migration step.
+- Bootstrap, Normalize or any unlayered reset can now be placed before the
+  components: `@layer bootstrap, gbs, app, utilities;`
+- Projects with no CSS framework need no change.
+
+See the Theming page, "Cascade layers", for the full model.
 
 ## Authors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbs-add-block",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "React Component Library",
   "type": "module",
   "files": [

package/source/beta-components/accordion/styles.css

@@ -4,13 +4,13 @@
  * Each section is a native <details>, so the marker has to be taken off (two
  * ways: `list-item` display in Firefox, the WebKit pseudo-element elsewhere)
  * before a chevron of our own goes on. Tokens read the shared --gbs-*
- * variables when they are set on an ancestor (set them on :root to theme every
- * component at once). Rules live in the `components` layer, so utility classes
- * passed through `className` / `classNames` override them.
+ * variables when they are set on an ancestor (set them on :root to theme
+ * every component at once). Rules live in the `gbs` layer; declare where it
+ * sits in your global CSS, e.g. `@layer reset, gbs, app, utilities;`, and
+ * anything in a later layer overrides them.
  */
-@layer theme, base, components, utilities;
 
-@layer components {
+@layer gbs {
   .ac-root {
     --ac-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
     --ac-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));

package/source/beta-components/alert/styles.css

@@ -3,12 +3,12 @@
  *
  * A banner that sits in the page, tinted by variant. Tokens read the shared
  * --gbs-* variables when they are set on an ancestor (set them on :root to
- * theme every component at once). Rules live in the `components` layer, so
- * utility classes passed through `className` / `classNames` override them.
+ * theme every component at once). Rules live in the `gbs` layer; declare
+ * where it sits in your global CSS, e.g. `@layer reset, gbs, app,
+ * utilities;`, and anything in a later layer overrides them.
  */
-@layer theme, base, components, utilities;
 
-@layer components {
+@layer gbs {
   .al-root {
     --al-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
     --al-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));

package/source/beta-components/avatar/styles.css

@@ -1,227 +1,226 @@
-/*
- * Avatar and AvatarGroup styles.
- *
- * The fallback colour comes from --av-hue-index, which the component sets from
- * a hash of the name: the same person is the same colour everywhere, and the
- * palette is generated rather than listed, so it follows a themed hue. Tokens
- * read the shared --gbs-* variables when they are set on an ancestor (set them
- * on :root to theme every component at once). Rules live in the `components`
- * layer, so utility classes passed through `className` / `classNames` override
- * them.
- */
-@layer theme, base, components, utilities;
-
-@layer components {
-  .av-root,
-  .av-group,
-  .av-overflow {
-    --av-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
-    --av-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
-    --av-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
-    --av-subtle: var(--gbs-subtle, light-dark(#f4f4f5, #1c1c20));
-    --av-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
-    --av-success: var(--gbs-success, light-dark(#15803d, #4ade80));
-    --av-warning: var(--gbs-warning, light-dark(#b45309, #fbbf24));
-    --av-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
-    --av-radius: var(--gbs-radius, var(--dg-radius, 8px));
-    --av-size: 32px;
-    --av-font-size: 13px;
-    --av-hue-index: 0;
-    /* Eight hues, 45° apart, starting at the blue end. */
-    --av-hue: calc(210 + var(--av-hue-index) * 45);
-
-    color-scheme: inherit;
-  }
-
-  :where(.dark, [data-theme="dark"]) :is(.av-root, .av-group, .av-overflow) {
-    color-scheme: dark;
-  }
-  :where(.light, [data-theme="light"]) :is(.av-root, .av-group, .av-overflow) {
-    color-scheme: light;
-  }
-
-  :where(.av-root, .av-group) *,
-  :where(.av-root, .av-group) *::before,
-  :where(.av-root, .av-group) *::after {
-    box-sizing: border-box;
-  }
-
-  .av-root {
-    position: relative;
-    display: inline-flex;
-    flex: none;
-    align-items: center;
-    justify-content: center;
-    width: var(--av-size);
-    height: var(--av-size);
-    border-radius: 50%;
-    background: var(--av-subtle);
-    font-size: var(--av-font-size);
-    font-weight: 600;
-    line-height: 1;
-    overflow: hidden;
-    user-select: none;
-    vertical-align: middle;
-  }
-  .av-root[data-shape="square"] {
-    border-radius: var(--av-radius);
-    overflow: visible;
-  }
-  .av-root[data-shape="square"] .av-image,
-  .av-root[data-shape="square"] .av-fallback {
-    border-radius: var(--av-radius);
-  }
-
-  .av-root[data-size="xs"] {
-    --av-size: 20px;
-    --av-font-size: 10px;
-  }
-  .av-root[data-size="sm"] {
-    --av-size: 24px;
-    --av-font-size: 11px;
-  }
-  .av-root[data-size="lg"] {
-    --av-size: 40px;
-    --av-font-size: 15px;
-  }
-  .av-root[data-size="xl"] {
-    --av-size: 56px;
-    --av-font-size: 20px;
-  }
-
-  .av-image {
-    width: 100%;
-    height: 100%;
-    object-fit: cover;
-  }
-
-  /* `oklch` keeps every hue at the same lightness, so no one person's initials
-     come out harder to read than another's — which is what a list of hand-picked
-     hex pairs always ends up doing. */
-  .av-fallback {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    width: 100%;
-    height: 100%;
-    background: oklch(from light-dark(oklch(0.93 0.05 0), oklch(0.32 0.06 0)) l c var(--av-hue));
-    color: oklch(from light-dark(oklch(0.42 0.13 0), oklch(0.88 0.1 0)) l c var(--av-hue));
-    text-transform: uppercase;
-  }
-  .av-fallback > svg {
-    width: 60%;
-    height: 60%;
-  }
-
-  .av-status {
-    position: absolute;
-    right: 0;
-    bottom: 0;
-    width: 30%;
-    height: 30%;
-    min-width: 8px;
-    min-height: 8px;
-    border: 2px solid var(--av-bg);
-    border-radius: 50%;
-    background: var(--av-muted);
-  }
-  .av-root[data-shape="square"] .av-status {
-    right: -2px;
-    bottom: -2px;
-  }
-  .av-status[data-status="online"] {
-    background: var(--av-success);
-  }
-  .av-status[data-status="away"] {
-    background: var(--av-warning);
-  }
-  .av-status[data-status="busy"] {
-    background: var(--av-danger);
-  }
-
-  /* ---------------------------------------------------------------- group */
-
-  .av-group {
-    display: inline-flex;
-    align-items: center;
-    vertical-align: middle;
-  }
-  /* Each face overlaps the one before and is ringed in the page colour, so the
-     stack reads as separate people rather than one smear. */
-  .av-group > * {
-    margin-inline-start: calc(var(--av-size) / -4);
-    box-shadow: 0 0 0 2px var(--av-bg);
-  }
-  .av-group > *:first-child {
-    margin-inline-start: 0;
-  }
-
-  .av-overflow {
-    position: relative;
-    display: inline-flex;
-    flex: none;
-    align-items: center;
-    justify-content: center;
-    width: var(--av-size);
-    height: var(--av-size);
-    border-radius: 50%;
-    background: var(--av-subtle);
-    /* Muted grey clears 4.5:1 on the page background but only reaches 4.39:1
-       on this one, so the count moves a step towards the text colour. */
-    color: color-mix(in oklab, var(--av-muted) 65%, var(--av-fg));
-    font-size: calc(var(--av-font-size) - 1px);
-    font-weight: 600;
-    font-variant-numeric: tabular-nums;
-    line-height: 1;
-  }
-  .av-overflow[data-shape="square"] {
-    border-radius: var(--av-radius);
-  }
-  .av-group[data-size="xs"],
-  .av-overflow[data-size="xs"] {
-    --av-size: 20px;
-    --av-font-size: 10px;
-  }
-  .av-group[data-size="sm"],
-  .av-overflow[data-size="sm"] {
-    --av-size: 24px;
-    --av-font-size: 11px;
-  }
-  .av-group[data-size="lg"],
-  .av-overflow[data-size="lg"] {
-    --av-size: 40px;
-    --av-font-size: 15px;
-  }
-  .av-group[data-size="xl"],
-  .av-overflow[data-size="xl"] {
-    --av-size: 56px;
-    --av-font-size: 20px;
-  }
-  /* The group's size reaches the avatars inside it, unless one sets its own. */
-  .av-group[data-size="xs"] .av-root:not([data-size]) {
-    --av-size: 20px;
-    --av-font-size: 10px;
-  }
-  .av-group[data-size="sm"] .av-root:not([data-size]) {
-    --av-size: 24px;
-    --av-font-size: 11px;
-  }
-  .av-group[data-size="lg"] .av-root:not([data-size]) {
-    --av-size: 40px;
-    --av-font-size: 15px;
-  }
-  .av-group[data-size="xl"] .av-root:not([data-size]) {
-    --av-size: 56px;
-    --av-font-size: 20px;
-  }
-
-  @media (forced-colors: active) {
-    .av-root,
-    .av-overflow {
-      border: 1px solid CanvasText;
-    }
-    .av-status {
-      border-color: Canvas;
-    }
-  }
-}
+/*
+ * Avatar and AvatarGroup styles.
+ *
+ * The fallback colour comes from --av-hue-index, which the component sets from
+ * a hash of the name: the same person is the same colour everywhere, and the
+ * palette is generated rather than listed, so it follows a themed hue. Tokens
+ * read the shared --gbs-* variables when they are set on an ancestor (set them
+ * on :root to theme every component at once). Rules live in the `components`
+ * layer, so utility classes passed through `className` / `classNames` override
+ * them.
+ */
+
+@layer gbs {
+  .av-root,
+  .av-group,
+  .av-overflow {
+    --av-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+    --av-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+    --av-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+    --av-subtle: var(--gbs-subtle, light-dark(#f4f4f5, #1c1c20));
+    --av-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+    --av-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+    --av-warning: var(--gbs-warning, light-dark(#b45309, #fbbf24));
+    --av-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+    --av-radius: var(--gbs-radius, var(--dg-radius, 8px));
+    --av-size: 32px;
+    --av-font-size: 13px;
+    --av-hue-index: 0;
+    /* Eight hues, 45° apart, starting at the blue end. */
+    --av-hue: calc(210 + var(--av-hue-index) * 45);
+
+    color-scheme: inherit;
+  }
+
+  :where(.dark, [data-theme="dark"]) :is(.av-root, .av-group, .av-overflow) {
+    color-scheme: dark;
+  }
+  :where(.light, [data-theme="light"]) :is(.av-root, .av-group, .av-overflow) {
+    color-scheme: light;
+  }
+
+  :where(.av-root, .av-group) *,
+  :where(.av-root, .av-group) *::before,
+  :where(.av-root, .av-group) *::after {
+    box-sizing: border-box;
+  }
+
+  .av-root {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    width: var(--av-size);
+    height: var(--av-size);
+    border-radius: 50%;
+    background: var(--av-subtle);
+    font-size: var(--av-font-size);
+    font-weight: 600;
+    line-height: 1;
+    overflow: hidden;
+    user-select: none;
+    vertical-align: middle;
+  }
+  .av-root[data-shape="square"] {
+    border-radius: var(--av-radius);
+    overflow: visible;
+  }
+  .av-root[data-shape="square"] .av-image,
+  .av-root[data-shape="square"] .av-fallback {
+    border-radius: var(--av-radius);
+  }
+
+  .av-root[data-size="xs"] {
+    --av-size: 20px;
+    --av-font-size: 10px;
+  }
+  .av-root[data-size="sm"] {
+    --av-size: 24px;
+    --av-font-size: 11px;
+  }
+  .av-root[data-size="lg"] {
+    --av-size: 40px;
+    --av-font-size: 15px;
+  }
+  .av-root[data-size="xl"] {
+    --av-size: 56px;
+    --av-font-size: 20px;
+  }
+
+  .av-image {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+
+  /* `oklch` keeps every hue at the same lightness, so no one person's initials
+     come out harder to read than another's — which is what a list of hand-picked
+     hex pairs always ends up doing. */
+  .av-fallback {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 100%;
+    background: oklch(from light-dark(oklch(0.93 0.05 0), oklch(0.32 0.06 0)) l c var(--av-hue));
+    color: oklch(from light-dark(oklch(0.42 0.13 0), oklch(0.88 0.1 0)) l c var(--av-hue));
+    text-transform: uppercase;
+  }
+  .av-fallback > svg {
+    width: 60%;
+    height: 60%;
+  }
+
+  .av-status {
+    position: absolute;
+    right: 0;
+    bottom: 0;
+    width: 30%;
+    height: 30%;
+    min-width: 8px;
+    min-height: 8px;
+    border: 2px solid var(--av-bg);
+    border-radius: 50%;
+    background: var(--av-muted);
+  }
+  .av-root[data-shape="square"] .av-status {
+    right: -2px;
+    bottom: -2px;
+  }
+  .av-status[data-status="online"] {
+    background: var(--av-success);
+  }
+  .av-status[data-status="away"] {
+    background: var(--av-warning);
+  }
+  .av-status[data-status="busy"] {
+    background: var(--av-danger);
+  }
+
+  /* ---------------------------------------------------------------- group */
+
+  .av-group {
+    display: inline-flex;
+    align-items: center;
+    vertical-align: middle;
+  }
+  /* Each face overlaps the one before and is ringed in the page colour, so the
+     stack reads as separate people rather than one smear. */
+  .av-group > * {
+    margin-inline-start: calc(var(--av-size) / -4);
+    box-shadow: 0 0 0 2px var(--av-bg);
+  }
+  .av-group > *:first-child {
+    margin-inline-start: 0;
+  }
+
+  .av-overflow {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    width: var(--av-size);
+    height: var(--av-size);
+    border-radius: 50%;
+    background: var(--av-subtle);
+    /* Muted grey clears 4.5:1 on the page background but only reaches 4.39:1
+       on this one, so the count moves a step towards the text colour. */
+    color: color-mix(in oklab, var(--av-muted) 65%, var(--av-fg));
+    font-size: calc(var(--av-font-size) - 1px);
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    line-height: 1;
+  }
+  .av-overflow[data-shape="square"] {
+    border-radius: var(--av-radius);
+  }
+  .av-group[data-size="xs"],
+  .av-overflow[data-size="xs"] {
+    --av-size: 20px;
+    --av-font-size: 10px;
+  }
+  .av-group[data-size="sm"],
+  .av-overflow[data-size="sm"] {
+    --av-size: 24px;
+    --av-font-size: 11px;
+  }
+  .av-group[data-size="lg"],
+  .av-overflow[data-size="lg"] {
+    --av-size: 40px;
+    --av-font-size: 15px;
+  }
+  .av-group[data-size="xl"],
+  .av-overflow[data-size="xl"] {
+    --av-size: 56px;
+    --av-font-size: 20px;
+  }
+  /* The group's size reaches the avatars inside it, unless one sets its own. */
+  .av-group[data-size="xs"] .av-root:not([data-size]) {
+    --av-size: 20px;
+    --av-font-size: 10px;
+  }
+  .av-group[data-size="sm"] .av-root:not([data-size]) {
+    --av-size: 24px;
+    --av-font-size: 11px;
+  }
+  .av-group[data-size="lg"] .av-root:not([data-size]) {
+    --av-size: 40px;
+    --av-font-size: 15px;
+  }
+  .av-group[data-size="xl"] .av-root:not([data-size]) {
+    --av-size: 56px;
+    --av-font-size: 20px;
+  }
+
+  @media (forced-colors: active) {
+    .av-root,
+    .av-overflow {
+      border: 1px solid CanvasText;
+    }
+    .av-status {
+      border-color: Canvas;
+    }
+  }
+}

package/source/beta-components/badge/styles.css

@@ -1,15 +1,15 @@
 /*
  * Badge and Tag styles.
  *
- * One tinted pill in six variants and three appearances; the variant only ever
- * sets --bd-accent, so adding one is a single rule. Tokens read the shared
- * --gbs-* variables when they are set on an ancestor (set them on :root to
- * theme every component at once). Rules live in the `components` layer, so
- * utility classes passed through `className` / `classNames` override them.
+ * One tinted pill in six variants and three appearances; the variant only
+ * ever sets --bd-accent, so adding one is a single rule. Tokens read the
+ * shared --gbs-* variables when they are set on an ancestor (set them on
+ * :root to theme every component at once). Rules live in the `gbs` layer;
+ * declare where it sits in your global CSS, e.g. `@layer reset, gbs, app,
+ * utilities;`, and anything in a later layer overrides them.
  */
-@layer theme, base, components, utilities;
 
-@layer components {
+@layer gbs {
   .bd-root,
   .bd-tag {
     --bd-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));