@ng-solid/design-system 22.2.2 → 22.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-solid/design-system",
-  "version": "22.2.2",
+  "version": "22.4.0",
   "license": "MIT",
   "description": "Arvisfy, the token-driven Angular design system for ng-solid.",
   "author": "Ulises Familia Rodríguez <chicromedia@hotmail.com>",

package/themes/README.md

@@ -53,11 +53,51 @@ export const ProductTheme = defineNsPreset(Arvisfy, {
 
 Tailwind utilities are composed from SCSS, never placed in ng-solid component
 templates. Consumers that want the same semantic utility bridge may import
-`@ng-solid/design-system/themes/tailwind.css` after Tailwind.
+`@ng-solid/design-system/themes/tailwind.css` after Tailwind; doing so also
+applies the box-sizing contract described below, though the kit assumes that
+contract regardless of whether the bridge is imported (see "Box model").
 
 Every component stylesheet starts with `@reference` to that bridge and reads
 only `--ns-component-*` variables for component-specific visual decisions.
 
+## Box model
+
+Arvisfy assumes `box-sizing: border-box` everywhere. `theme/tailwind.css`
+restates the `box-sizing` declaration from Tailwind v4's preflight, on that
+preflight's exact selector:
+
+```css
+*,
+::before,
+::after,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+}
+```
+
+It is copied literally rather than `@import`ed, because ng-packagr ships this
+file as a plain asset — an `@import` would reach the consumer unresolved. The
+rest of preflight's box-sizing block (`margin/padding/border: 0` on every
+element) is intentionally left out: unlike this single, additive rule, it is
+destructive to markup that doesn't expect it.
+
+Three properties follow from that choice:
+
+- **Idempotent.** Applications that already load Tailwind's own preflight (or
+  any other reset that sets the same rule) see no change — selector and
+  declaration are identical.
+- **Zero added specificity.** The universal selector `*` (and the
+  pseudo-elements listed alongside it) contributes no specificity, so any
+  consumer rule, however plain, overrides it trivially. It is a default, not
+  an imposition.
+- **Opt-in scope.** Consumers who don't import the bridge are covered only
+  where a component's own SCSS declares `box-sizing` locally; the
+  workspace-wide default lives solely inside `tailwind.css`.
+
+An audit across 53 playground pages found that adopting this rule eliminated
+17 real overflow bugs and introduced none.
+
 ## HeroUI foundations
 
 Arvisfy vendors Inter Variable in `theme/fonts/InterVariable.woff2` (with its
@@ -73,3 +113,34 @@ maps to `light`. Components own their state tokens (for example
 `--ns-component-slider-*` and `--ns-component-input-search-*`) rather than
 borrowing another component's variables; use the matching family when adding
 a visual decision.
+
+## Retired tokens
+
+A token is retired when no component stylesheet reads its `--ns-component-*`
+variable anymore, but it still ships as a published field of the preset —
+removing the field outright would silently break any consumer override that
+still targets it. `NsTokenTree` has an open index signature, so an override
+of a retired (or otherwise unknown) key merges in cleanly with no type error
+and no `validateNsPreset` error; it just has no effect.
+
+To surface that instead of letting it fail silently, `theme/utils/theme.utils.ts`
+keeps a small internal `NS_RETIRED_TOKENS` map of retired token paths to a
+warning message, and `validateNsPreset` emits a `console.warn` for each one
+still present in the resolved preset. This does not throw — an inert override
+should not crash a consumer's app — and it is not deduplicated across calls,
+so it warns every time a preset containing the retired path is validated.
+
+The registry lives inside `theme.utils.ts` itself rather than its own file:
+`packages/mcp`'s data extraction transpiles that file in isolation and cannot
+resolve a relative value import from a sibling module at that point (see
+`assertNoValueImports` in `packages/mcp/scripts/lib/extract-tokens.mjs`), so a
+separate `retired-tokens.ts` imported for its data would break
+`nx run mcp:build-data`.
+
+Currently retired:
+
+- `components.imageUpload.thumbnailSize` — used to size each stack thumbnail
+  and (indirectly) the height of `ns-image-upload[layout="cover"]`. Since the
+  height fix in AVF-29, `components.imageUpload.emptyMinHeight` alone sizes
+  that layout in both its empty and filled states, and no stylesheet reads
+  `--ns-component-image-upload-thumbnail-size` anymore.

package/themes/tailwind.css

@@ -1,3 +1,18 @@
+/* This bridge ships as a raw asset (ng-package.json) and ng-packagr copies it
+   byte-for-byte to consumers, with no PostCSS pass — so it cannot `@import`
+   Tailwind's preflight (that import would reach consumers unresolved).
+   Instead this literally reproduces just the `box-sizing: border-box` line
+   from Tailwind v4's preflight (node_modules/tailwindcss/preflight.css),
+   intentionally omitting the accompanying margin/padding/border reset, which
+   would be destructive to existing markup. */
+*,
+::before,
+::after,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+}
+
 @font-face {
   font-family: 'Inter Variable';
   font-style: normal;