kmcom-nuxt-layers 6.0.0 → 6.1.0

package/docs/adr/0003-modular-step-system-replaces-fluid-clamps.md

@@ -0,0 +1,58 @@
+# 0003 — One modular step scale replaces the fluid type and spacing clamps
+
+Status: accepted (2026-10-20)
+
+## Context
+
+Type and spacing were two unrelated sets of hand-tuned `clamp()` ranges: 13 `text-fluid-*`
+utilities (plus 13 `-cq` copies) snapped by `round(down, …, 0.25rem)`, and 8 `--fluid-space-*`
+tokens (plus 7 `-cq` copies). No ratio linked one size to the next, so every new size was
+another clamp to tune, and the `-cq` sets had no consumers. The reference system (matuzo.at,
+analysed in `matuzo-typography-system-1.md`) gets better proportions from two ratios.
+
+## Decision
+
+Every size is a step on a scale:
+
+- **Type:** `font-size = round(--type-base × 1.26^--step, 0.0625rem)`. Base is `1rem` below
+  48rem and `1.2rem` from 48rem; body is step 1 (20 → 24px). `h1` uses a fluid display step,
+  5 → 7 across 360 → 1280px, cast from a length with `tan(atan2(…, 1rem))`. Utilities are
+  `text-step-sm`, `text-step-0` … `text-step-12`, `text-step-display`.
+- **Space:** `--space-* = --space-base × 1.414^n`, with `--space-base` running 11.3 → 16px
+  across 320 → 1280px — one step of growth, not the reference's two (8 → 16px), so phones keep
+  the old token sizes. The `Spacing` union is unchanged; only the values behind it moved.
+- **Grid:** the `grid` layer's `--fs` shares the type scale's endpoint tokens (`--type-min`,
+  `--type-max`) but stays continuous, so its rhythm unit does not inherit the 48rem jump.
+
+It is a parallel namespace: Tailwind's `--text-*`, Nuxt UI's `--ui-*` and the `html` font-size
+are untouched. Tokens are plain `:root` properties, not `@theme`, so `var(--step)` resolves on
+the element using it.
+
+## Consequences
+
+- The top end is coarser: `TypographyHeadline` levels step down from the fluid display step
+  (97/77/61/48/38/30px at 1280px, 51 → 16px at 320px) instead of the old 144/120/96/76/36/24px,
+  which also overflowed phone widths. Plain h1–h6 use the reading scale (display, 3, 2, 1, 0, 0).
+- Step line heights fall smoothly with size (sm 1.5 … body 1.7, h2/h3 1.2 … display 0.95) and
+  now reach components: `useTypography` only emits `leading-*` when asked.
+- Body text grows from 16px to 20/24px, and body line-height from 1.5 to 1.7. Nuxt UI
+  components with explicit `text-*` sizes are unaffected; anything that inherits body size
+  (card bodies, plain prose) grows. Heading defaults skip `[data-slot]` headings, so Nuxt UI's
+  own titles (UModal, USlideover) inherit instead of jumping to a heading step.
+- Every step jumps ×1.2 at 48rem because the base switches there (h1 ≈ 62 → 75px at 768px).
+- Spacing matches the old tokens on phones and stays close on desktop for xs–xl; 2xl/3xl top out
+  smaller than before (64/90px vs 80/112px).
+- `--space-*` steps are substituted at `:root`, so per-subtree spacing retuning is not
+  supported. Type retuning is: `--type-base` and `--type-scale` are read per element.
+- The display step is normalised by `1rem` and its `vw` term is scaled by root / 16px, so its
+  exponent depends only on viewport width and every size grows with a larger root font size.
+  (Unscaled, the exponent fell as the root grew: h1 was only 1.02× larger at a 24px root.)
+- The old `--heading-text-scale-damp` multiplier is gone. As written it enlarged steps ≥ 7
+  under OS text-scale > 100% instead of damping them; a true damp would break "visibly larger
+  at a larger root".
+- `--fs` stays unregistered: a registered `<length>` holding `rem` on `:root`, read by the
+  root's own line-height, is a dependency cycle in Gecko that freezes the grid unit.
+- Nuxt UI prose is retuned onto the scale (typography `app.config.ts`): prose headings take
+  steps (h1 4, h2 3, h3 2, h4 1) and `p`/`li` keep the body's 1.7 leading. Otherwise the
+  24px copy sat at or above Nuxt UI's fixed `text-2xl`/`text-xl` prose headings. This needs
+  `text-step-*` registered as a font-size group in tailwind-merge (`ui.tv.twMergeConfig`).

package/layers/core/app/assets/css/tokens/spacing-fluid.css

@@ -1,25 +1,30 @@
 /**
- * Fluid spacing scale — clamp() + cqi container-relative variant, same
- * pattern as layers/typography's fluid type scale (see typography.css).
+ * Fluid spacing scale — one ratio, same idea as typography.css's type scale:
+ *   space = --space-base × --space-scale ^ n
+ * 1.414 ≈ 2^(1/2), so two steps double a gap. --space-base runs 11.3px at ≤320px to 16px
+ * at ≥1280px — one step of growth (√2), not the reference's two (8 → 16px), so phones keep
+ * the old fluid tokens' sizes (xs 8 · md 16 · xl 32 · 3xl 64px at 320px). The rem term in the
+ * middle keeps it zoom-safe (WCAG 1.4.4).
  * Backs the `Spacing` token (layers/core/app/types/tokens.ts) consumed by
- * useLayoutAttrs(). --fluid-space-none is 0, not clamp() — no scaling needed.
+ * useLayoutAttrs(). --space-none is 0, not a step.
+ * Plain :root properties, not @theme: --space-* is not a Tailwind namespace, and
+ * xs/md/xl declared there would risk colliding with --container-* size names.
+ *
+ * Trap: each step substitutes --space-base here at :root, so overriding --space-base
+ * on a subtree does NOT change --space-md inside it. Per-subtree spacing retuning is
+ * not a supported extension point (type retuning is — see typography.css).
  */
 :root {
-  --fluid-space-none: 0px;
-  --fluid-space-xs: clamp(0.5rem, 0.46rem + 0.2vi, 0.625rem);
-  --fluid-space-sm: clamp(0.75rem, 0.7rem + 0.25vi, 1rem);
-  --fluid-space-md: clamp(1rem, 0.9rem + 0.5vi, 1.5rem);
-  --fluid-space-lg: clamp(1.5rem, 1.3rem + 1vi, 2.5rem);
-  --fluid-space-xl: clamp(2rem, 1.7rem + 1.5vi, 3.5rem);
-  --fluid-space-2xl: clamp(3rem, 2.4rem + 3vi, 5rem);
-  --fluid-space-3xl: clamp(4rem, 3rem + 5vi, 7rem);
+  --space-scale: 1.414;
+  --space-base: clamp(0.7071rem, 0.6095rem + 0.4882vw, 1rem);
 
-  /* Container-relative counterparts (cqi) — opt-in inside a `container-type` ancestor. */
-  --fluid-space-xs-cq: clamp(0.5rem, 0.46rem + 2cqi, 0.625rem);
-  --fluid-space-sm-cq: clamp(0.75rem, 0.65rem + 2.5cqi, 1rem);
-  --fluid-space-md-cq: clamp(1rem, 0.8rem + 5cqi, 1.5rem);
-  --fluid-space-lg-cq: clamp(1.5rem, 1.1rem + 10cqi, 2.5rem);
-  --fluid-space-xl-cq: clamp(2rem, 1.4rem + 15cqi, 3.5rem);
-  --fluid-space-2xl-cq: clamp(3rem, 2rem + 25cqi, 5rem);
-  --fluid-space-3xl-cq: clamp(4rem, 2.5rem + 37.5cqi, 7rem);
+  /* n = −1 … 5 */
+  --space-none: 0px;
+  --space-xs: calc(var(--space-base) * pow(var(--space-scale), -1));
+  --space-sm: calc(var(--space-base) * pow(var(--space-scale), 0));
+  --space-md: calc(var(--space-base) * pow(var(--space-scale), 1));
+  --space-lg: calc(var(--space-base) * pow(var(--space-scale), 2));
+  --space-xl: calc(var(--space-base) * pow(var(--space-scale), 3));
+  --space-2xl: calc(var(--space-base) * pow(var(--space-scale), 4));
+  --space-3xl: calc(var(--space-base) * pow(var(--space-scale), 5));
 }

package/layers/core/app/components/Element.test.ts

@@ -69,8 +69,8 @@ describe('Element', () => {
       props: { m: 'md', p: 'lg' },
     })
     const style = wrapper.attributes('style') ?? ''
-    expect(style).toContain('margin: var(--fluid-space-md)')
-    expect(style).toContain('padding: var(--fluid-space-lg)')
+    expect(style).toContain('margin: var(--space-md)')
+    expect(style).toContain('padding: var(--space-lg)')
   })
 
   it('passes componentProps to the resolved component, past a colliding prop name', () => {

package/layers/core/app/composables/useLayoutAttrs.test.ts

@@ -1,21 +1,51 @@
+import { readFileSync } from 'node:fs'
+
 import { describe, expect, it } from 'vite-plus/test'
 
+import type { Spacing } from '../types/tokens'
 import { useLayoutAttrs } from './useLayoutAttrs'
 
+// spacingVar() builds the custom-property name by string interpolation, so a token
+// with no matching declaration resolves to an undefined var() — silent in CSS.
+describe('useLayoutAttrs spacing tokens', () => {
+  const css = readFileSync(
+    new URL('../assets/css/tokens/spacing-fluid.css', import.meta.url),
+    'utf8'
+  )
+  // Record, not an array, so typecheck fails if the Spacing union gains a member.
+  const tokens: Record<Exclude<Spacing, 'none'>, true> = {
+    xs: true,
+    sm: true,
+    md: true,
+    lg: true,
+    xl: true,
+    '2xl': true,
+    '3xl': true,
+  }
+
+  it('resolves every token to a property spacing-fluid.css declares', () => {
+    for (const token of Object.keys(tokens) as Spacing[]) {
+      const { style } = useLayoutAttrs(() => ({ gap: token }))
+      const name = /^var\((--[\w-]+)\)$/.exec(String(style.value.gap))?.[1]
+      expect(css).toMatch(new RegExp(`^\\s*${name}:`, 'm'))
+    }
+  })
+})
+
 describe('useLayoutAttrs margin support', () => {
   it('sets margin from a static token', () => {
     const { style } = useLayoutAttrs(() => ({ m: 'md' }))
-    expect(style.value.margin).toBe('var(--fluid-space-md)')
+    expect(style.value.margin).toBe('var(--space-md)')
   })
 
   it('sets marginInline from px-equivalent mx', () => {
     const { style } = useLayoutAttrs(() => ({ mx: 'lg' }))
-    expect(style.value.marginInline).toBe('var(--fluid-space-lg)')
+    expect(style.value.marginInline).toBe('var(--space-lg)')
   })
 
   it('sets marginBlock from my', () => {
     const { style } = useLayoutAttrs(() => ({ my: 'sm' }))
-    expect(style.value.marginBlock).toBe('var(--fluid-space-sm)')
+    expect(style.value.marginBlock).toBe('var(--space-sm)')
   })
 
   it('resolves none to 0px for margin', () => {
@@ -38,8 +68,8 @@ describe('useLayoutAttrs margin support', () => {
       p: 'lg',
     }))
     expect(style.value).toEqual({
-      gap: 'var(--fluid-space-md)',
-      padding: 'var(--fluid-space-lg)',
+      gap: 'var(--space-md)',
+      padding: 'var(--space-lg)',
       alignItems: 'center',
       justifyContent: 'space-between',
     })

package/layers/core/app/composables/useLayoutAttrs.ts

@@ -47,7 +47,7 @@ function resolveDefault<T>(value: ResponsiveValue<T> | T | undefined): T | undef
 }
 
 function spacingVar(token: Spacing): string {
-  return token === 'none' ? '0px' : `var(--fluid-space-${token})`
+  return token === 'none' ? '0px' : `var(--space-${token})`
 }
 
 function applySpacing(

package/layers/core/app/utils/resolveElementStyle.test.ts

@@ -87,9 +87,9 @@ describe('resolveElementStyle prop mapping', () => {
   it('merges layout attrs (gap/align/padding) into the same object', () => {
     expect(resolveElementStyle({ flex: true, gap: 'md', align: 'center', p: 'sm' })).toMatchObject({
       display: 'flex',
-      gap: 'var(--fluid-space-md)',
+      gap: 'var(--space-md)',
       alignItems: 'center',
-      padding: 'var(--fluid-space-sm)',
+      padding: 'var(--space-sm)',
     })
   })
 

package/layers/design-system/theming/app/types/designSystem.ts

@@ -7,19 +7,21 @@
  * (theme adapter component overrides, standalone token exports) will import
  * it directly.
  */
-import type { FluidFontSize } from '#layers/typography/app/types/typography'
+import type { TypeStep } from '#layers/typography/app/types/typography'
 import type { UiColors } from '#types'
 
 /**
  * Design-system tokens — first real config-object source of truth (Phase 5,
  * nuxt-declarative-layout-system-spec.md §21). Colours key off the existing
  * `UiColors` union rather than inventing new names; typography keys off the
- * existing `FluidFontSize` scale/CSS vars in layers/typography — this section
+ * existing `TypeStep` modular scale/CSS vars in layers/typography — this section
  * only gives them a config-object home so a Nuxt UI theme adapter and CSS
  * custom properties can derive from one place.
  */
 
-const fluidTextVar = (size: FluidFontSize) => `var(--fluid-text-${size}-raw)`
+// Unrounded size of one step — typography.css's text-step-* utilities also round() it.
+const stepSize = (exponent: number | string) =>
+  `calc(var(--type-base) * pow(var(--type-scale), ${exponent}))`
 
 export const designSystem = {
   colors: {
@@ -59,20 +61,22 @@ export const designSystem = {
   },
 
   typography: {
-    xs: fluidTextVar('xs'),
-    sm: fluidTextVar('sm'),
-    md: fluidTextVar('md'),
-    lg: fluidTextVar('lg'),
-    xl: fluidTextVar('xl'),
-    '2xl': fluidTextVar('2xl'),
-    '3xl': fluidTextVar('3xl'),
-    '4xl': fluidTextVar('4xl'),
-    '5xl': fluidTextVar('5xl'),
-    '6xl': fluidTextVar('6xl'),
-    '7xl': fluidTextVar('7xl'),
-    '8xl': fluidTextVar('8xl'),
-    '9xl': fluidTextVar('9xl'),
-  },
+    sm: stepSize(-1),
+    0: stepSize(0),
+    1: stepSize(1),
+    2: stepSize(2),
+    3: stepSize(3),
+    4: stepSize(4),
+    5: stepSize(5),
+    6: stepSize(6),
+    7: stepSize(7),
+    8: stepSize(8),
+    9: stepSize(9),
+    10: stepSize(10),
+    11: stepSize(11),
+    12: stepSize(12),
+    display: stepSize('var(--step-display)'),
+  } satisfies Record<TypeStep, string>,
 
   motion: {
     duration: {

package/layers/design-system/typography/app/app.config.ts

@@ -0,0 +1,26 @@
+import { TYPE_STEP_CLASSES } from './composables/typography'
+
+// Nuxt UI prose (Nuxt Content) on the modular scale. Nuxt UI pins prose headings to
+// text-4xl/2xl/xl/lg and p/li to leading-7 with no size, so with a 20/24px body the copy sat
+// at or above h2/h3 size on a cramped 28px line. Headings take their step instead (h1 one step
+// above h2, not the display step — content pages already show a page-header title); copy keeps
+// inheriting the body step, with the body's 1.7 leading.
+export default defineAppConfig({
+  ui: {
+    // tailwind-merge reads unknown text-* classes as a text colour, so a step class would drop
+    // a component's colour class and keep its text-{size}. Register them as font sizes.
+    tv: {
+      twMergeConfig: {
+        extend: { classGroups: { 'font-size': Object.values(TYPE_STEP_CLASSES) } },
+      },
+    },
+    prose: {
+      h1: { slots: { base: 'text-step-4' } },
+      h2: { slots: { base: 'text-step-3' } },
+      h3: { slots: { base: 'text-step-2' } },
+      h4: { slots: { base: 'text-step-1' } },
+      p: { base: 'leading-[1.7]' },
+      li: { base: 'leading-[1.7]' },
+    },
+  },
+})