zz-meridian 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.24.0] · 2026-10-20
+
+### New
+
+- **First-load JS can be held to each route's baseline alone** ([#76](https://github.com/zhixuan312/zz-meridian/issues/76)), as every page's HTML is since 0.19.0. Set `budgets.firstLoadKb: null` in `scripts/verify.config.ts`: a route `scripts/verify.baseline.json` holds is then held to `firstLoadGrowthPct` over its own figure and nothing else, and the 820 KiB cap binds only a route the baseline does not hold yet. A product whose largest page sits near the cap no longer fails `pnpm verify` for a change its own baseline allows, and no longer derives a cap from the baseline to say the same rule twice. Leaving the key out keeps the cap on every route, as before; the size line says which applies (`cap 820 KiB for a route the baseline does not hold`).
+
+## [0.23.0] · 2026-10-20
+
+### New
+
+- **`Prose` names each body cell's column, and stacks a narrow table into labelled cards** ([#75](https://github.com/zhixuan312/zz-meridian/issues/75)). Every body `td` carries its column's heading as `data-label`, written while the markdown is rendered, so it is in the server's HTML and a page can style a narrow table from `td[data-label]` on the first paint, with no second markdown parser. `stack` does it for you: a table under 480px of its own width reads as one card per row, the header row hidden, the first cell the title and each later cell under its column's heading. Wider, it is the same table; without `stack`, nothing changes.
+
 ## [0.22.0] · 2026-10-20
 
 ### New

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. Six layers, from DTCG tokens through four layers of React components to product workspaces, and a Design Atlas, in a light and a dark theme.",

package/payload/scripts/lib/budgets.ts

@@ -24,7 +24,8 @@ export type NavigationCheck = {
 };
 export type Budgets = {
   navigation: { warm: ReadinessBudget; cold: ReadinessBudget; afterLive: ReadinessBudget };
-  firstLoadKb: number;
+  /** `null`: each route the baseline holds is held to it alone, and the default cap binds only a route it does not. */
+  firstLoadKb: number | null;
   firstLoadGrowthPct: number;
   htmlGrowthPct: number;
   htmlKb: Record<string, number>;
@@ -33,7 +34,7 @@ export type Budgets = {
 export type BudgetsConfig = {
   budgets?: {
     navigation?: { warm?: ReadinessBudget; cold?: ReadinessBudget; afterLive?: ReadinessBudget };
-    firstLoadKb?: number;
+    firstLoadKb?: number | null;
     firstLoadGrowthPct?: number;
     htmlGrowthPct?: number;
     htmlKb?: Record<string, number>;
@@ -47,6 +48,9 @@ const COLD: ReadinessBudget = {
   interactiveMs: { desktop: 2000, phone: 4000 },
 };
 
+/** The first-load cap, in KiB, for a route the baseline does not hold, and for every route unless `firstLoadKb` is null. */
+export const FIRST_LOAD_CAP_KB = 820;
+
 /** Each page's HTML is held to its own baseline; an absolute HTML cap is a project's route, so the defaults set none. */
 export const DEFAULT_BUDGETS: Budgets = {
   navigation: {
@@ -58,7 +62,7 @@ export const DEFAULT_BUDGETS: Budgets = {
     cold: COLD,
     afterLive: COLD,
   },
-  firstLoadKb: 820,
+  firstLoadKb: FIRST_LOAD_CAP_KB,
   firstLoadGrowthPct: 5,
   htmlGrowthPct: 5,
   htmlKb: {},
@@ -92,7 +96,7 @@ export function budgetsOf(config: BudgetsConfig): Budgets {
   const cold = b.navigation?.cold ?? DEFAULT_BUDGETS.navigation.cold;
   return {
     navigation: { warm, cold, afterLive: b.navigation?.afterLive ?? cold },
-    firstLoadKb: b.firstLoadKb ?? DEFAULT_BUDGETS.firstLoadKb,
+    firstLoadKb: b.firstLoadKb === null ? null : b.firstLoadKb ?? DEFAULT_BUDGETS.firstLoadKb,
     firstLoadGrowthPct: b.firstLoadGrowthPct ?? DEFAULT_BUDGETS.firstLoadGrowthPct,
     htmlGrowthPct: b.htmlGrowthPct ?? DEFAULT_BUDGETS.htmlGrowthPct,
     htmlKb: b.htmlKb ?? DEFAULT_BUDGETS.htmlKb,

package/payload/scripts/lib/sizes.ts

@@ -19,16 +19,20 @@ export function firstLoad(
   });
 }
 
-/** Routes over the cap or past their growth allowance over a baseline; without a baseline growth is not configured. */
+/**
+ * Routes over the cap or past their growth allowance over a baseline; without a baseline growth is not configured.
+ * `capUnheldOnly` holds a route the baseline holds to its baseline alone, so the cap binds only a route it does not.
+ */
 export function firstLoadProblems(
   routes: { route: string; bytes: number }[],
-  { capKiB, growthPct, baseline }: { capKiB: number; growthPct: number; baseline: Record<string, number> | null },
+  { capKiB, growthPct, baseline, capUnheldOnly = false }: { capKiB: number; growthPct: number; baseline: Record<string, number> | null; capUnheldOnly?: boolean },
 ): { problems: string[]; growth: 'checked' | 'not-configured' } {
   const problems: string[] = [];
   for (const { route, bytes } of routes) {
-    if (bytes > capKiB * KIB) problems.push(`${route}: first-load JS ${kib(bytes)} KiB over the ${capKiB} KiB cap`);
     const base = baseline?.[route];
-    if (base === undefined || base <= 0) continue;
+    const held = base !== undefined && base > 0;
+    if (!(capUnheldOnly && held) && bytes > capKiB * KIB) problems.push(`${route}: first-load JS ${kib(bytes)} KiB over the ${capKiB} KiB cap`);
+    if (!held) continue;
     const grew = ((bytes - base) / base) * 100;
     if (grew > growthPct) problems.push(`${route}: first-load JS grew ${grew.toFixed(1)}% over its baseline (cap ${growthPct}%)`);
   }

package/payload/scripts/sizes.ts

@@ -6,7 +6,8 @@
  *
  * First-load comes from the build's own `diagnostics/route-bundle-stats.json`, read once, with each chunk's size from
  * disk: every chunk a route loads counted once, uncompressed. It is checked against `budgets.firstLoadKb` and, when
- * `scripts/verify.baseline.json` exists, against `budgets.firstLoadGrowthPct` over it. A page's HTML is what a person
+ * `scripts/verify.baseline.json` exists, against `budgets.firstLoadGrowthPct` over it; with `firstLoadKb: null` a route
+ * the baseline holds is held to it alone, and the default cap binds only a route it does not. A page's HTML is what a person
  * downloads: the complete streamed response from the app running at `--base`, gzipped. Every page in the baseline's
  * `html` is held to `budgets.htmlGrowthPct` over its own figure, and a route in `budgets.htmlKb` also to that absolute
  * cap. Without a baseline a growth check is `not-configured`, a warning and never a pass; without `--base` the HTML is
@@ -28,7 +29,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { gzipSync } from 'node:zlib';
 
-import { budgetsOf, type BudgetsConfig } from './lib/budgets.ts';
+import { FIRST_LOAD_CAP_KB, budgetsOf, type BudgetsConfig } from './lib/budgets.ts';
 import { distDirOf } from './lib/next-config.ts';
 import { firstLoad, firstLoadProblems, htmlGrowthProblems, htmlProblems, htmlRoutes } from './lib/sizes.ts';
 import verifyConfig from './verify.config.ts';
@@ -112,11 +113,12 @@ async function main(): Promise<number> {
 
   const budgets = budgetsOf(verifyConfig as BudgetsConfig);
   const baseline = baselineOf();
-  const size = firstLoadProblems(routes, { capKiB: budgets.firstLoadKb, growthPct: budgets.firstLoadGrowthPct, baseline: baseline?.firstLoad ?? null });
+  const capKiB = budgets.firstLoadKb ?? FIRST_LOAD_CAP_KB;
+  const size = firstLoadProblems(routes, { capKiB, growthPct: budgets.firstLoadGrowthPct, baseline: baseline?.firstLoad ?? null, capUnheldOnly: budgets.firstLoadKb === null });
   const largest = routes.reduce((a, b) => (b.bytes > a.bytes ? b : a), routes[0]);
   const lines: string[] = [];
   const firstStatus: Status = size.problems.length ? 'FAIL' : size.growth === 'not-configured' ? 'warn' : 'ok';
-  lines.push(`${firstStatus === 'FAIL' ? 'FAIL   ' : firstStatus === 'warn' ? 'warn   ' : 'ok     '} first-load ${routes.length} routes, largest ${largest.route} ${kib(largest.bytes)} KiB · cap ${budgets.firstLoadKb} KiB`
+  lines.push(`${firstStatus === 'FAIL' ? 'FAIL   ' : firstStatus === 'warn' ? 'warn   ' : 'ok     '} first-load ${routes.length} routes, largest ${largest.route} ${kib(largest.bytes)} KiB · cap ${capKiB} KiB${budgets.firstLoadKb === null ? ' for a route the baseline does not hold' : ''}`
     + ` · growth ${size.growth === 'checked' ? `within ${budgets.firstLoadGrowthPct}% of the baseline` : 'not-configured (no scripts/verify.baseline.json)'}`);
   for (const p of size.problems) lines.push(`FAIL    ${p}`);
 

package/payload/scripts/verify.config.ts

@@ -101,11 +101,12 @@ type VerifyConfig = {
    * `scripts/verify.baseline.json`, the warm, cold and after-live navigation times, and no prefetch on a closed phone drawer.
    * Every page's HTML, gzipped through the end of the streamed response, is held to `htmlGrowthPct` (5%) over its own
    * figure in the baseline's `html`; `htmlKb` adds an absolute cap in KiB, the same gzipped figure, for a page a project
-   * wants pinned, and has no default.
+   * wants pinned, and has no default. `firstLoadKb: null` holds first-load JS the same way: each route the baseline holds
+   * to its own figure alone, with the default cap binding only a route the baseline does not hold yet.
    */
   budgets?: {
     navigation?: { warm?: ReadinessBudget; cold?: ReadinessBudget; afterLive?: ReadinessBudget };
-    firstLoadKb?: number;
+    firstLoadKb?: number | null;
     firstLoadGrowthPct?: number;
     htmlGrowthPct?: number;
     htmlKb?: Record<string, number>;

package/payload/src/components/patterns/prose/README.md

@@ -10,7 +10,7 @@ Status: beta
 2. **Headings**: the writer's `#` is an h2 (`text-xl`), `##` an h3 with a hairline above it, `###` an h4: the page keeps the only h1.
 3. **Lists**: discs and numbers in `ink-3`; task boxes drawn as checkboxes named "Done" or "Not done".
 4. **Code**: inline on `surface-sunk` with a `line` border; a fenced block on `surface-sunk`, `radius-lg`, wrapping instead of scrolling.
-5. **Tables**: inside a `line`-bordered frame, a `surface-sunk` header row, `text-sm` cells.
+5. **Tables**: inside a `line`-bordered frame, a `surface-sunk` header row, `text-sm` cells. Every body cell carries its column's heading as `data-label`, in the server's HTML. With `stack`, a table under 480px of its own width reads as one card per row: the header row hidden, the first cell the title in `ink`, each later cell under its heading in `text-xs` `ink-3`.
 6. **Quote**: a 2px `accent` rule on the left, `ink` text.
 7. **Links**: `.link`, in `accent-ink`, turning `ink` on hover, never underlined; a link out of the product sends no referrer.
 
@@ -34,6 +34,7 @@ A markdown string. Line endings are normalised and the ends trimmed; nothing els
 | An image from another origin | Its alt text in italics (or "Image not shown"), never fetched |
 | A long token in code or a link: a URL, a path, a hash | Breaks anywhere rather than widen its paragraph or table; plain words wrap between words |
 | A table with more columns than the card holds | Scrolls inside its own frame; the page never scrolls sideways |
+| `stack`, and a table under 480px of its own width | One card per row, each value under its column's heading; no header row |
 | Empty | Nothing: the caller shows the empty state ("No notes yet") |
 
 ## Surfaces
@@ -71,4 +72,7 @@ import { Prose } from '@/components/patterns/prose';
 
 <Card className="p-(--card-pad)"><Prose>{incident.review}</Prose></Card>
 <Prose size="sm">{comment.body}</Prose>
+<Prose stack>{decision.record}</Prose>   // tables become labelled cards in a narrow column
 ```
+
+`stack` is for a document whose tables carry sentences (a decision record, a comparison) read in a narrow column. A table of short figures reads better scrolling in its frame, which is the default. Without `stack`, a page can still style its own narrow layout from `td[data-label]`.

package/payload/src/components/patterns/prose/index.tsx

@@ -1,4 +1,4 @@
-import { memo } from 'react';
+import { memo, type ReactNode } from 'react';
 import ReactMarkdown, { type Components } from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { cn } from '@/lib/cn';
@@ -7,6 +7,25 @@ import { safeMarkdownUrl } from '@/lib/safe-markdown';
 /** A link that leaves the product sends no referrer: the reader's address is not the author's business. */
 const external = (href?: string) => Boolean(href && /^(https?:)?\/\//i.test(href));
 
+type Hast = { type: string; tagName?: string; value?: string; properties?: Record<string, unknown>; children?: Hast[] };
+const text = (n: Hast): string => n.value ?? (n.children ?? []).map(text).join('');
+const elements = (n: Hast, tag: string): Hast[] => (n.children ?? []).flatMap((c) => (c.tagName === tag ? [c] : c.tagName === 'table' ? [] : elements(c, tag)));
+
+/**
+ * Each body cell carries its column's heading as `data-label`, written while the markdown is turned into HTML, so a
+ * table can be read as labelled cards with CSS alone on the server's first paint. A cell past the last heading, or
+ * under an empty one, carries none.
+ */
+const labelCells = () => (tree: Hast) => {
+  for (const table of elements({ type: 'root', children: [tree] }, 'table')) {
+    const headings = elements(table, 'th').map((th) => text(th).trim());
+    for (const tr of elements(table, 'tbody').flatMap((b) => elements(b, 'tr')))
+      elements(tr, 'td').forEach((td, i) => {
+        if (headings[i]) td.properties = { ...td.properties, dataLabel: headings[i] };
+      });
+  }
+};
+
 /**
  * Markdown a person wrote (a document, a note, an agent's reply), set for reading on Meridian's roles: a 72-character
  * measure, quiet tables, code on the sunk surface. Each element is drawn here rather than by a typography plugin, so
@@ -39,7 +58,7 @@ const COMPONENTS: Components = {
   thead: ({ children }) => <thead className="border-b border-line bg-surface-sunk">{children}</thead>,
   th: ({ children }) => <th className="px-3 py-2 text-xs font-medium whitespace-nowrap text-ink-3">{children}</th>,
   tr: ({ children }) => <tr className="border-b border-line last:border-0">{children}</tr>,
-  td: ({ children }) => <td className="px-3 py-2.5 align-top text-ink-2">{children}</td>,
+  td: ({ children, 'data-label': label }: { children?: ReactNode; 'data-label'?: string }) => <td data-label={label} className="px-3 py-2.5 align-top text-ink-2">{children}</td>,
   blockquote: ({ children }) => <blockquote className="my-4 border-l-2 border-accent pl-4 text-ink">{children}</blockquote>,
   hr: () => <hr className="my-8 border-line" />,
   // An image the URL policy dropped reads as its alt text, never as a broken-image icon.
@@ -52,10 +71,36 @@ const COMPONENTS: Components = {
     rest.type === 'checkbox' ? <input {...rest} aria-label={rest.checked ? 'Done' : 'Not done'} className="mr-2 size-3.5 align-[-2px] accent-(--accent)" /> : <input {...rest} />),
 };
 
-export const Prose = memo(function Prose({ children, size = 'base', className }: { children: string; /** `sm` for a side panel, a comment or a quoted body. */ size?: 'base' | 'sm'; className?: string }) {
+/**
+ * `stack`: below 480px of its own width a table reads as one card per row: the header row hidden, the first cell the
+ * card's title, each later cell on its own line under its column's heading. The frame is the container, so a table in a
+ * narrow column stacks wherever the column is narrow, not only on a phone.
+ */
+const STACKED: Components = {
+  ...COMPONENTS,
+  table: ({ children }) => (
+    <div className="my-5 overflow-x-auto rounded-lg border border-line @container">
+      <table className={cn('w-full text-left text-sm leading-normal',
+        '@max-[480px]:block @max-[480px]:[&>thead]:hidden @max-[480px]:[&>tbody]:block @max-[480px]:[&_tr]:block @max-[480px]:[&_tr]:px-3 @max-[480px]:[&_tr]:py-2.5',
+        '@max-[480px]:[&_td]:block @max-[480px]:[&_td]:p-0 @max-[480px]:[&_td+td]:mt-2 @max-[480px]:[&_td:first-child]:font-medium @max-[480px]:[&_td:first-child]:text-ink',
+        '@max-[480px]:[&_td:not(:first-child)[data-label]]:before:block @max-[480px]:[&_td:not(:first-child)[data-label]]:before:text-xs @max-[480px]:[&_td:not(:first-child)[data-label]]:before:font-medium @max-[480px]:[&_td:not(:first-child)[data-label]]:before:text-ink-3 @max-[480px]:[&_td:not(:first-child)[data-label]]:before:content-[attr(data-label)]')}>
+        {children}
+      </table>
+    </div>
+  ),
+};
+
+export const Prose = memo(function Prose({ children, size = 'base', stack = false, className }: {
+  children: string;
+  /** `sm` for a side panel, a comment or a quoted body. */
+  size?: 'base' | 'sm';
+  /** A table narrower than 480px reads as labelled cards, one per row. */
+  stack?: boolean;
+  className?: string;
+}) {
   return (
     <div className={cn('min-w-0 text-ink-2 break-words', size === 'base' ? 'text-base leading-[1.7]' : 'text-sm leading-relaxed', className)}>
-      <ReactMarkdown remarkPlugins={[remarkGfm]} urlTransform={safeMarkdownUrl} components={COMPONENTS}>
+      <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[labelCells]} urlTransform={safeMarkdownUrl} components={stack ? STACKED : COMPONENTS}>
         {children.replace(/\r\n/g, '\n').trim()}
       </ReactMarkdown>
     </div>

package/payload/src/components/patterns/prose/preview.tsx

@@ -40,6 +40,11 @@ const HOSTILE = `A reply pasted from somewhere else:
 
 ![A tracking pixel](https://elsewhere.example/pixel.png)`;
 
+const DECISIONS = `| Choice | Chosen | Rejected because |
+|---|---|---|
+| Queue | Postgres \`SKIP LOCKED\` | a broker is one more service to run for 40 jobs a minute |
+| Retries | Three, with backoff | a fourth retry has never succeeded in the last 90 days |`;
+
 export default function ProsePreview() {
   return (
     <>
@@ -58,6 +63,14 @@ export default function ProsePreview() {
           <div className="w-80 p-4"><Prose size="sm">{REVIEW.split('## What we are changing')[1]}</Prose></div>
         </Plane>
       </Specimen>
+      <Specimen label="Stacked" note="With stack, a table under 480px of its own width reads as one card per row: the first cell its title, each later cell under its column's heading. Wider, it is the same table." stack>
+        <Plane on="surface">
+          <div className="flex flex-wrap gap-6 p-4">
+            <div className="w-80"><Prose size="sm" stack>{DECISIONS}</Prose></div>
+            <div className="w-[560px] max-w-full"><Prose size="sm" stack>{DECISIONS}</Prose></div>
+          </div>
+        </Plane>
+      </Specimen>
     </>
   );
 }

package/payload/tests/prose-cell-labels.test.tsx

@@ -0,0 +1,31 @@
+import { render } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { Prose } from '@/components/patterns/prose';
+
+const DOC = `| Choice | Chosen | Rejected because |
+|---|---|---|
+| Store | **Postgres** | the queue needs order |
+| Cache | none | |
+
+| A | \`B\` |
+|---|---|
+| 1 | 2 | 3 |`;
+
+describe('Prose names each body cell\'s column (#75)', () => {
+  test('writes the column heading on every body cell, per table, as plain text', () => {
+    const { container } = render(<Prose>{DOC}</Prose>);
+    const [first, second] = [...container.querySelectorAll('table')];
+    expect([...first.querySelectorAll('tbody td')].map((td) => td.getAttribute('data-label'))).toEqual(['Choice', 'Chosen', 'Rejected because', 'Choice', 'Chosen', 'Rejected because']);
+    expect([...second.querySelectorAll('tbody td')].map((td) => td.getAttribute('data-label'))).toEqual(['A', 'B']);
+    expect(container.querySelectorAll('th[data-label]')).toHaveLength(0);
+  });
+
+  test('stack makes each table\'s frame the container its rows stack in', () => {
+    const plain = render(<Prose>{DOC}</Prose>);
+    expect(plain.container.querySelector('.\\@container')).toBeNull();
+    plain.unmount();
+    const { container } = render(<Prose stack>{DOC}</Prose>);
+    expect(container.querySelectorAll('.\\@container > table')).toHaveLength(2);
+    expect(container.querySelector('tbody td')).toHaveAttribute('data-label', 'Choice');
+  });
+});

package/payload/tests/verify-sizes.test.ts

@@ -22,6 +22,13 @@ describe('first-load JS', () => {
     expect(firstLoadProblems([{ route: '/y', bytes: 535 * KiB }], { capKiB: 820, growthPct: 5, baseline: null })).toEqual({ problems: [], growth: 'not-configured' });
     expect(firstLoadProblems([{ route: '/y', bytes: 535 * KiB }], { capKiB: 1, growthPct: 5, baseline: null }).problems).toHaveLength(1);
   });
+  it('with the cap for unheld routes only, holds a route the baseline holds to its baseline alone (#76)', () => {
+    const routes = [{ route: '/x', bytes: 852 * KiB }, { route: '/y', bytes: 900 * KiB }, { route: '/z', bytes: 700 * KiB }];
+    const got = firstLoadProblems(routes, { capKiB: 820, growthPct: 5, baseline: { '/x': 850 * KiB, '/z': 600 * KiB }, capUnheldOnly: true });
+    expect(got.problems).toEqual(['/y: first-load JS 900 KiB over the 820 KiB cap', '/z: first-load JS grew 16.7% over its baseline (cap 5%)']);
+    expect(budgetsOf({ budgets: { firstLoadKb: null } }).firstLoadKb).toBeNull();
+    expect(budgetsOf({}).firstLoadKb).toBe(820);
+  });
 });
 
 describe('HTML and prefetch', () => {