@archetypeai/ds-cli 0.15.0 → 0.16.1

package/README.md

@@ -138,7 +138,7 @@ The configuration is two files: the instruction file (`CLAUDE.md`/`AGENTS.md`
 
 ## Fonts
 
-The `--fonts <path>` flag expects a local folder containing all 15 PP Neue Montreal files (9 Sans `.ttf` + 6 Mono `.otf`). The CLI validates the folder and copies the files to `static/fonts/`, where the `@font-face` declarations in `@archetypeai/ds-lib-tokens/fonts.css` expect them. With `--no-fonts`, the theme falls back to system fonts.
+The `--fonts <path>` flag expects a local folder containing all 13 PP Neue Montreal `.woff2` files (8 Sans + 5 Mono). The CLI validates the folder and copies the files to `static/fonts/`, where the `@font-face` declarations in `@archetypeai/ds-lib-tokens/fonts.css` expect them. With `--no-fonts`, the theme falls back to system fonts.
 
 ## Registries
 

package/commands/create.js

@@ -12,7 +12,11 @@ import {
   createDemoPage,
   installAgentConfig
 } from '../lib/scaffold-ds-svelte-project.js';
-import { validateFontsPath, installLocalFonts } from '../lib/install-fonts-local.js';
+import {
+  validateFontsPath,
+  installLocalFonts,
+  preloadLinkTags
+} from '../lib/install-fonts-local.js';
 import { isInteractive, DEFAULTS } from '../lib/is-interactive.js';
 
 // parse flags
@@ -250,6 +254,14 @@ export async function create(args) {
     const fontResult = installLocalFonts(fontsPath, projectPath);
     if (fontResult.success) {
       s.stop(`${fontResult.fileCount} font files installed`);
+      if (fontResult.preload.patched) {
+        p.log.info('Preloading Book, Medium and Mono Book in src/app.html');
+      } else {
+        p.log.warn(
+          `Could not add font preloads (${fontResult.preload.reason}). Add these to your <head>:\n` +
+            preloadLinkTags().join('\n')
+        );
+      }
     } else {
       s.stop('Failed to install fonts');
       p.log.warn(fontResult.error);

package/commands/init.js

@@ -11,7 +11,11 @@ import {
   installLinting,
   installAgentConfig
 } from '../lib/scaffold-ds-svelte-project.js';
-import { validateFontsPath, installLocalFonts } from '../lib/install-fonts-local.js';
+import {
+  validateFontsPath,
+  installLocalFonts,
+  preloadLinkTags
+} from '../lib/install-fonts-local.js';
 import { isInteractive, DEFAULTS } from '../lib/is-interactive.js';
 
 // parse flags
@@ -210,6 +214,14 @@ export async function init(args) {
     const fontResult = installLocalFonts(fontsPath, projectPath);
     if (fontResult.success) {
       s.stop(`${fontResult.fileCount} font files installed`);
+      if (fontResult.preload.patched) {
+        p.log.info('Preloading Book, Medium and Mono Book in src/app.html');
+      } else {
+        p.log.warn(
+          `Could not add font preloads (${fontResult.preload.reason}). Add these to your <head>:\n` +
+            preloadLinkTags().join('\n')
+        );
+      }
     } else {
       s.stop('Failed to install fonts');
       p.log.warn(fontResult.error);

package/files/AGENTS.md

@@ -81,6 +81,25 @@ use them decoratively.
 
 ## Typography
 
+The theme pairs every `text-*` step with its own line-height and letter-spacing
+(`--text-sm--line-height`, `--text-sm--letter-spacing`, …), so `text-sm` alone
+is on-brand. Never add `leading-*` or `tracking-*` next to a `text-*` utility —
+the ramp already supplies both. `text-2xs` (10px) is the floor for dense
+metadata; never use arbitrary sizes like `text-[11px]`.
+
+The theme's base layer styles only authored-content elements: `body` (14px
+sans), `h1`–`h6` (30px → 14px, `h4`–`h6` muted, `h1` title-cased), `p`,
+`small`, `strong`, `blockquote`, plus `cursor-pointer` on `a`. It deliberately
+does **not** style `span`, `label`, `em`, `code` or `pre` — and gives `a` no
+typography either — they inherit from their parent, so set the size once on the
+parent instead of on every inline child (`code`/`pre` get the mono family from
+Tailwind preflight and stay the same size as their text). Bare links are
+visually flat until you style them, but every `a` shows the pointer cursor even
+without an `href`; use the `Label` primitive for labels.
+`h1` is `capitalize` by default (use `normal-case` for ids or sentence-case
+copy); uppercase belongs to `Label` variants and `typography="mono"`, never to
+a heading.
+
 Default to sans for all text. `font-mono` is reserved for exactly two cases:
 
 - Primitives that already use it in the design system source of truth (their
@@ -110,8 +129,9 @@ darkMode.toggle(); // switch
 darkMode.current; // reactive read
 ```
 
-Gotcha: `CodeBlock` highlights once on mount — wrap it in
-`{#key darkMode.current}` so it re-highlights on theme flips.
+`CodeBlock` needs nothing here: it highlights with both themes at once (shiki
+emits the dark colours as `--shiki-dark` custom props) and flips them in CSS, so
+theme switches need no `{#key}` wrapper and no re-highlight.
 
 ## Page shell
 
@@ -173,6 +193,9 @@ Compose project-specific components from package primitives in
   `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
   types but are internal to the Archetype AI console product — never use them
 - Keep the `@source` directives and the CSS import order exactly as above
+- Never add global element rules (`span`, `a`, `label`, `p`, `h1`…) in app CSS,
+  and never pair `leading-*`/`tracking-*` with a `text-*` utility — the theme's
+  type scale and base layer own both; size a parent, not its inline children
 - Never style scrollbars in app code — no `::-webkit-scrollbar` rules, no
   `scrollbar-color`/`scrollbar-width`. The theme sets both, and setting
   `scrollbar-*` locally also silently disables the webkit pseudo-elements on

package/files/CLAUDE.md

@@ -81,6 +81,25 @@ use them decoratively.
 
 ## Typography
 
+The theme pairs every `text-*` step with its own line-height and letter-spacing
+(`--text-sm--line-height`, `--text-sm--letter-spacing`, …), so `text-sm` alone
+is on-brand. Never add `leading-*` or `tracking-*` next to a `text-*` utility —
+the ramp already supplies both. `text-2xs` (10px) is the floor for dense
+metadata; never use arbitrary sizes like `text-[11px]`.
+
+The theme's base layer styles only authored-content elements: `body` (14px
+sans), `h1`–`h6` (30px → 14px, `h4`–`h6` muted, `h1` title-cased), `p`,
+`small`, `strong`, `blockquote`, plus `cursor-pointer` on `a`. It deliberately
+does **not** style `span`, `label`, `em`, `code` or `pre` — and gives `a` no
+typography either — they inherit from their parent, so set the size once on the
+parent instead of on every inline child (`code`/`pre` get the mono family from
+Tailwind preflight and stay the same size as their text). Bare links are
+visually flat until you style them, but every `a` shows the pointer cursor even
+without an `href`; use the `Label` primitive for labels.
+`h1` is `capitalize` by default (use `normal-case` for ids or sentence-case
+copy); uppercase belongs to `Label` variants and `typography="mono"`, never to
+a heading.
+
 Default to sans for all text. `font-mono` is reserved for exactly two cases:
 
 - Primitives that already use it in the design system source of truth (their
@@ -110,8 +129,9 @@ darkMode.toggle(); // switch
 darkMode.current; // reactive read
 ```
 
-Gotcha: `CodeBlock` highlights once on mount — wrap it in
-`{#key darkMode.current}` so it re-highlights on theme flips.
+`CodeBlock` needs nothing here: it highlights with both themes at once (shiki
+emits the dark colours as `--shiki-dark` custom props) and flips them in CSS, so
+theme switches need no `{#key}` wrapper and no re-highlight.
 
 ## Page shell
 
@@ -173,6 +193,9 @@ Compose project-specific components from package primitives in
   `sideBarSelection`, `lensTray*`, `backToDashboard`) exist in the package
   types but are internal to the Archetype AI console product — never use them
 - Keep the `@source` directives and the CSS import order exactly as above
+- Never add global element rules (`span`, `a`, `label`, `p`, `h1`…) in app CSS,
+  and never pair `leading-*`/`tracking-*` with a `text-*` utility — the theme's
+  type scale and base layer own both; size a parent, not its inline children
 - Never style scrollbars in app code — no `::-webkit-scrollbar` rules, no
   `scrollbar-color`/`scrollbar-width`. The theme sets both, and setting
   `scrollbar-*` locally also silently disables the webkit pseudo-elements on

package/files/ds-manifest.json

@@ -1,6 +1,6 @@
 {
 	"name": "archetypeai-design-system",
-	"version": "0.15.0",
+	"version": "0.16.1",
 	"components": [
 		{
 			"name": "alert",
@@ -245,8 +245,8 @@
 			"source": "https://design-system-console.archetypeai.workers.dev/r/codeblock.json",
 			"description": "Syntax-highlighted code display (CodeBlock, shiki; yaml/json/python/shell) and editable code field with JSON-schema validation for YAML (CodeBlockEditor).",
 			"usage": [
-				"`<CodeBlock code language=\"yaml\" />` for read-only code (border built in). `language` accepts `\"yaml\" | \"json\" | \"python\" | \"shell\"` — use `\"shell\"` for bash/sh/curl snippets. Theme switches are CSS-only — no {#key} wrapper needed. Grows to content by default; to cap the height pass `maxHeight=\"20rem\"` (any CSS length) or the `scroll` shorthand (=600px) — this puts the scrollbar on the internal scroller, whereas a `max-h-*` class on the component clips without scrolling. `showLineNumbers={false}` hides the gutter; `wrap` wraps long lines instead of scrolling horizontally.",
-				"Config editors: `<CodeBlockEditor bind:value bind:valid bind:validating bind:schemaUnavailable schema={jsonSchema} placeholder showDownload downloadBaseName disabled />` + a status badge row driven by the bindables (validating → 'Checking…' spinner; !valid → 'Invalid'; valid+schemaUnavailable → 'YAML parses'; valid → 'Valid YAML'). Grows to content (floor via `minHeight`, default 10rem); cap+scroll via `maxHeight` (any length) or `scroll` (=600px). Visually identical to CodeBlock. `language` (same union, default `\"yaml\"`) switches highlighting; live validation runs only for `\"yaml\"` — for other languages `schema` is ignored and `valid` stays true. The download button's extension/MIME follows the language (.yaml/.json/.py/.sh)."
+				"`<CodeBlock code language=\"yaml\" />` for read-only code (border built in). `language` accepts `\"yaml\" | \"json\" | \"python\" | \"shell\"` — use `\"shell\"` for bash/sh/curl snippets. Theme switches are CSS-only — no {#key} wrapper needed. Grows to content by default and never clips: whenever its height is constrained — by a `max-h-*` class, by a flex/grid parent like `Dialog.Body`, or by the `maxHeight`/`scroll` props — the internal scroller shows a scrollbar instead. To cap it yourself pass `maxHeight=\"20rem\"` (any CSS length) or the `scroll` shorthand (=600px); neither is needed just to avoid clipping. `showLineNumbers={false}` hides the gutter; `wrap` wraps long lines instead of scrolling horizontally.",
+				"Config editors: `<CodeBlockEditor bind:value bind:valid bind:validating bind:schemaUnavailable schema={jsonSchema} placeholder showDownload downloadBaseName disabled />` + a status badge row driven by the bindables (validating → 'Checking…' spinner; !valid → 'Invalid'; valid+schemaUnavailable → 'YAML parses'; valid → 'Valid YAML'). Grows to content (floor via `minHeight`, default 10rem) and scrolls rather than clips whenever its height is constrained; cap it yourself via `maxHeight` (any length) or `scroll` (=600px). Visually identical to CodeBlock. `language` (same union, default `\"yaml\"`) switches highlighting; live validation runs only for `\"yaml\"` — for other languages `schema` is ignored and `valid` stays true. The download button's extension/MIME follows the language (.yaml/.json/.py/.sh)."
 			]
 		},
 		{
@@ -357,7 +357,8 @@
 			"usage": [
 				"Trigger via child snippet spread onto a Button (profile menu: `variant=\"accent\"` avatar + chevron, rounded-full).",
 				"Styled triggers: `DropdownMenu.Trigger variant=\"filter\"` for toolbar/list filter dropdowns; `variant=\"input\"` for form-field-styled dropdowns in pickers.",
-				"`DropdownMenu.Content align=\"end\" class=\"min-w-64\"`; items `justify=\"between\"` with a trailing icon; `closeOnSelect={false}` for in-menu toggles (dark mode); Separator before Sign Out."
+				"`DropdownMenu.Content align=\"end\" class=\"min-w-64\"`; items `justify=\"between\"` with a trailing icon; `closeOnSelect={false}` for in-menu toggles (dark mode); Separator before Sign Out.",
+				"Section headings: `DropdownMenu.Label` for a standalone heading, `DropdownMenu.GroupHeading` inside a `Group`. Both render in the console's section-header treatment by default (10px mono, uppercase, muted, more space above than below so the heading binds to the rows it introduces), so a heading recedes rather than competing with its items. Set no type or colour classes on them; if a Label is carrying a row of content rather than a heading, override with `class`."
 			],
 			"variants": {
 				"dropdownMenuTriggerVariants": {
@@ -907,6 +908,55 @@
 				"Horizontal between stacked sections; `orientation=\"vertical\"` in multi-column layouts."
 			]
 		},
+		{
+			"name": "side-panel",
+			"import": "@archetypeai/ds-ui-svelte-console/primitives/side-panel",
+			"source": "https://design-system-console.archetypeai.workers.dev/r/side-panel.json",
+			"description": "Non-modal side panel for peeking at or inspecting one object without leaving the list it came from.",
+			"usage": [
+				"Bind the panel to an object id, never to a row: `<SidePanel.Root open={selectedId !== null} onOpenChange={(o) => !o && (selectedId = null)}>`. Keep the id in the URL so the state survives refresh, back and sharing; the primitive itself never reads or writes the URL. Do NOT derive the panel's content straight from that id: the panel stays mounted while it closes, so the content would blank out before it leaves. Latch the last opened object instead, `let shown = $state(null); $effect(() => { const next = find(selectedId); if (next) shown = next; })`, and render from `shown`.",
+				"Peek vs inspect: content with no page of its own just fills `SidePanel.Body`. Content that has a full page renders the page's body component inside Body and puts the handoff ONCE, in the Header `actions` snippet, as an outline icon button beside the built-in Close: `<SidePanel.Header>{#snippet actions()}<Button variant=\"outline\" size=\"icon\" class=\"size-8\" aria-label=\"Open full page\" href={fullPageUrl}><ArrowUpRightIcon /></Button>{/snippet}<SidePanel.Title>…</SidePanel.Title></SidePanel.Header>`. Header actions are outline icon buttons at the sm height (`class=\"size-8\"`, Button has no small icon size) so they read as one set with Close, pinned to the header's top-right, and match `size=\"sm\"` Footer buttons; never repeat the handoff in the Footer.",
+				"It never renders an overlay or scrim and never traps focus or scroll: the list behind stays fully interactive, clicking outside does nothing, Escape closes. If the task needs the page blocked, use Dialog instead.",
+				"One panel at a time. Drilling in replaces Body's content and adds an in-panel back; it never opens a second SidePanel.",
+				"Read-mostly: actions inside are fine, but destructive confirmations spawn a Dialog over the panel. The panel does not own confirmation.",
+				"`size=\"sm\"` (384px) for a record and its fields; `size=\"md\"` (576px) when Body carries a preview, a chart or a code block. `side=\"left\"` only when the list itself lives on the right.",
+				"Header layout follows Dialog: a `space-y-2` block, so `SidePanel.Title` and then either `SidePanel.Description` (plain text) or `SidePanel.Meta` (badges, a status line, key/value metadata) stack full width. The `actions` cluster and the close sit absolutely at the top right, so the header reserves right padding and a long Title truncates rather than running under them. Give header actions the same bare icon treatment as the close via `sidePanelCloseButtonVariants`; keep `Description` when the subtitle is text, because it is what wires `aria-describedby` and `Meta` cannot.",
+				"Content renders in place (no portal) so Tab reaches it after the list; do not mount it inside a transformed ancestor, where `fixed` misplaces. Focus does not move on open. Header renders an outline icon Close by default (`showCloseButton={false}` to place `SidePanel.Close` yourself). `SidePanel.Footer` is optional: it holds the actions on the data being viewed, never Close or the full-page handoff. One primary action sits right; with `justify=\"between\"` secondary actions (copy an id, compare) go first and land left."
+			],
+			"variants": {
+				"sidePanelContentVariants": {
+					"axes": {
+						"side": [
+							"right",
+							"left"
+						],
+						"size": [
+							"sm",
+							"md"
+						],
+						"mode": [
+							"overlay"
+						]
+					},
+					"defaults": {
+						"side": "right",
+						"size": "sm",
+						"mode": "overlay"
+					}
+				},
+				"sidePanelFooterVariants": {
+					"axes": {
+						"justify": [
+							"default",
+							"between"
+						]
+					},
+					"defaults": {
+						"justify": "default"
+					}
+				}
+			}
+		},
 		{
 			"name": "slider",
 			"import": "@archetypeai/ds-ui-svelte-labs/primitives/slider",
@@ -996,7 +1046,8 @@
 			"usage": [
 				"Log/event tables: width-classed Table.Head columns, `Table.Body class=\"font-sans text-xs\"`, level cells colored with status tokens (text-atai-critical for error rows).",
 				"Mono body (`typography=\"mono\"` on Table.Body) for id-heavy tables; pair with `EmptyState variant=\"list\"` when empty.",
-				"Header rows never take the data-row hover — `Table.Header` neutralizes it; don't cancel `hover:bg-*` from consumer code."
+				"Header rows never take the data-row hover — `Table.Header` neutralizes it; don't cancel `hover:bg-*` from consumer code.",
+				"Sortable columns: `Table.Head sortable direction={col === sort ? order : null} onSort={() => setSort(col)}`. The primitive owns the affordance, the three-state indicator and `aria-sort`; the consumer owns the sort state, so a Sort menu and the headers can drive the same state and stay in step. Mark only the columns the API can actually order by. Non-sortable heads are unchanged and simply are not clickable."
 			],
 			"variants": {
 				"tableBodyVariants": {
@@ -1009,6 +1060,44 @@
 					"defaults": {
 						"typography": "default"
 					}
+				},
+				"tableHeadVariants": {
+					"axes": {
+						"sortable": [
+							"true",
+							"false"
+						]
+					},
+					"defaults": {
+						"sortable": "false"
+					}
+				},
+				"tableHeadSortVariants": {
+					"axes": {
+						"active": [
+							"true",
+							"false"
+						]
+					},
+					"defaults": {
+						"active": "false"
+					}
+				},
+				"tableHeadSortIconVariants": {
+					"axes": {
+						"active": [
+							"true",
+							"false"
+						],
+						"flipped": [
+							"true",
+							"false"
+						]
+					},
+					"defaults": {
+						"active": "false",
+						"flipped": "false"
+					}
 				}
 			}
 		},
@@ -1127,9 +1216,10 @@
 			"description": "Hover hint.",
 			"usage": [
 				"Wrap the app/section in `Tooltip.Provider delayDuration={200}`.",
-				"Field help: `Tooltip.Trigger variant=\"info\"` is a filled 20px disc holding a mono `i` — pass it no children, it renders its own glyph. Explanation goes in `Tooltip.Content`.",
+				"Field help: `Tooltip.Trigger variant=\"info\"` is a filled 16px disc holding a mono `i` — pass it no children, it renders its own glyph. Explanation goes in `Tooltip.Content`.",
 				"`aria-label` on the info trigger is required and is the caller's: name what is being explained (`aria-label=\"About Detection Log\"`). The glyph is `aria-hidden`, so without a label the button has no accessible name.",
-				"The info disc squares against `Counter`'s height on purpose — a list title, its `Counter` and its info disc in one `flex items-center gap-2` row is the intended cluster, the solid pill reading as the count and the muted one as the meaning.",
+				"The info disc squares against `Counter size=\"sm\"`'s height on purpose — a section title, its `Counter` and its info disc in one `flex items-center gap-2` row is the intended cluster, the solid pill reading as the count and the muted one as the meaning. 16px is also exactly the height of a `Label variant=\"sectionHeader\"` box, so the disc sits level with the title rather than towering over it.",
+				"`size=\"lg\"` is the 20px disc, for a cluster built around `Counter size=\"default\"` (`h-5`) rather than a section label. `size` is inert on the other trigger treatments, which have no box.",
 				"`variant=\"inlineLink\"` — underlined trigger flowing inside prose (supported file requirements).",
 				"The arrow centres itself on the trigger on all four sides and protrudes half its box — `arrowClasses` is for its ink or size, not for centring corrections. If a tip looks off, it is a bug in `tooltipArrowVariants`, not something to counter-shift at the call site."
 			],
@@ -1140,10 +1230,15 @@
 							"default",
 							"info",
 							"inlineLink"
+						],
+						"size": [
+							"default",
+							"lg"
 						]
 					},
 					"defaults": {
-						"variant": "default"
+						"variant": "default",
+						"size": "default"
 					}
 				}
 			}

package/lib/add-ds-lib-tokens.js

@@ -2,7 +2,7 @@ import { execFile } from 'child_process';
 import { promisify } from 'util';
 import * as p from '@clack/prompts';
 import { detectPm, getPm } from './use-package-manager.js';
-import { validateFontsPath, installLocalFonts } from './install-fonts-local.js';
+import { validateFontsPath, installLocalFonts, preloadLinkTags } from './install-fonts-local.js';
 import { isInteractive } from './is-interactive.js';
 import { prependCss } from './scaffold-ds-svelte-project.js';
 
@@ -124,6 +124,14 @@ export async function addDsLibTokens(args) {
     const fontResult = installLocalFonts(fontsPath, projectDir);
     if (fontResult.success) {
       fontSpinner.stop(`${fontResult.fileCount} font files installed`);
+      if (fontResult.preload.patched) {
+        p.log.info('Preloading Book, Medium and Mono Book in src/app.html');
+      } else {
+        p.log.warn(
+          `Could not add font preloads (${fontResult.preload.reason}). Add these to your <head>:\n` +
+            preloadLinkTags().join('\n')
+        );
+      }
     } else {
       fontSpinner.stop('Failed to install fonts');
       p.log.warn(fontResult.error);

package/lib/add-ds-ui-svelte.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'url';
 import * as p from '@clack/prompts';
 import { validateRegistryUrl } from './validate-url.js';
 import { detectPm, getPm } from './use-package-manager.js';
-import { validateFontsPath, installLocalFonts } from './install-fonts-local.js';
+import { validateFontsPath, installLocalFonts, preloadLinkTags } from './install-fonts-local.js';
 import { isInteractive } from './is-interactive.js';
 import {
   prependCss,
@@ -177,6 +177,14 @@ export async function addDsUiSvelte(args) {
       const fontResult = installLocalFonts(fontsPath, projectDir);
       if (fontResult.success) {
         fontSpinner.stop(`${fontResult.fileCount} font files installed`);
+        if (fontResult.preload.patched) {
+          p.log.info('Preloading Book, Medium and Mono Book in src/app.html');
+        } else {
+          p.log.warn(
+            `Could not add font preloads (${fontResult.preload.reason}). Add these to your <head>:\n` +
+              preloadLinkTags().join('\n')
+          );
+        }
       } else {
         fontSpinner.stop('Failed to install fonts');
         p.log.warn(fontResult.error);

package/lib/install-fonts-local.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, copyFileSync, mkdirSync } from 'fs';
+import { existsSync, readdirSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 
 // strip surrounding quotes that some terminals (VS Code, Cursor) add on drag-and-drop
@@ -13,25 +13,59 @@ function sanitizePath(p) {
   return trimmed;
 }
 
-// all 15 required font files
+// all 13 required font files
 export const REQUIRED_FONTS = [
-  // PP Neue Montreal Sans (.ttf)
-  'PPNeueMontreal-Thin.ttf',
-  'PPNeueMontreal-ThinItalic.ttf',
-  'PPNeueMontreal-Light.ttf',
-  'PPNeueMontreal-Book.ttf',
-  'PPNeueMontreal-Italic.ttf',
-  'PPNeueMontreal-Medium.ttf',
-  'PPNeueMontreal-Bold.ttf',
-  'PPNeueMontreal-BoldItalic.ttf',
-  // PP Neue Montreal Mono (.otf)
-  'PPNeueMontrealMono-Thin.otf',
-  'PPNeueMontrealMono-Book.otf',
-  'PPNeueMontrealMono-RegularItalic.otf',
-  'PPNeueMontrealMono-Medium.otf',
-  'PPNeueMontrealMono-Bold.otf'
+  // PP Neue Montreal Sans
+  'PPNeueMontreal-Thin.woff2',
+  'PPNeueMontreal-ThinItalic.woff2',
+  'PPNeueMontreal-Light.woff2',
+  'PPNeueMontreal-Book.woff2',
+  'PPNeueMontreal-Italic.woff2',
+  'PPNeueMontreal-Medium.woff2',
+  'PPNeueMontreal-Bold.woff2',
+  'PPNeueMontreal-BoldItalic.woff2',
+  // PP Neue Montreal Mono
+  'PPNeueMontrealMono-Thin.woff2',
+  'PPNeueMontrealMono-Book.woff2',
+  'PPNeueMontrealMono-RegularItalic.woff2',
+  'PPNeueMontrealMono-Medium.woff2',
+  'PPNeueMontrealMono-Bold.woff2'
 ];
 
+// the faces the first paint uses: 400 sans (body), 500 sans (emphasis), 400 mono (labels)
+export const FONT_PRELOADS = [
+  'PPNeueMontreal-Book.woff2',
+  'PPNeueMontreal-Medium.woff2',
+  'PPNeueMontrealMono-Book.woff2'
+];
+
+// `crossorigin` is required on font preloads even same-origin; without it the
+// browser fetches the file twice (once anonymous for the preload, once CORS for @font-face)
+export function preloadLinkTags() {
+  return FONT_PRELOADS.map(
+    (file) => `<link rel="preload" as="font" type="font/woff2" crossorigin href="/fonts/${file}" />`
+  );
+}
+
+// insert the preload tags above %sveltekit.head% in src/app.html (idempotent)
+export function patchAppHtmlPreload(projectPath) {
+  const htmlPath = join(projectPath, 'src', 'app.html');
+  if (!existsSync(htmlPath)) return { patched: false, reason: 'src/app.html not found' };
+  const content = readFileSync(htmlPath, 'utf-8');
+  if (content.includes(`/fonts/${FONT_PRELOADS[0]}`)) {
+    return { patched: false, reason: 'preload tags already present' };
+  }
+  const marker = /^([ \t]*)%sveltekit\.head%/m;
+  const match = content.match(marker);
+  if (!match) return { patched: false, reason: '%sveltekit.head% placeholder not found' };
+  const indent = match[1];
+  const tags = preloadLinkTags()
+    .map((tag) => `${indent}${tag}\n`)
+    .join('');
+  writeFileSync(htmlPath, content.replace(marker, `${tags}${indent}%sveltekit.head%`));
+  return { patched: true };
+}
+
 // validate that a directory contains all required font files
 export function validateFontsPath(fontsPath) {
   const resolved = resolve(sanitizePath(fontsPath));
@@ -72,7 +106,7 @@ export function copyFontsToStatic(fontsPath, projectPath) {
   return REQUIRED_FONTS.length;
 }
 
-// orchestrate: validate and copy font files to static/fonts/
+// orchestrate: validate, copy font files to static/fonts/, and preload the first-paint faces
 export function installLocalFonts(fontsPath, projectPath) {
   const validation = validateFontsPath(fontsPath);
   if (!validation.valid) {
@@ -80,6 +114,7 @@ export function installLocalFonts(fontsPath, projectPath) {
   }
 
   const fileCount = copyFontsToStatic(fontsPath, projectPath);
+  const preload = patchAppHtmlPreload(projectPath);
 
-  return { success: true, fileCount };
+  return { success: true, fileCount, preload };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archetypeai/ds-cli",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Archetype AI Design System CLI Tool",
   "type": "module",
   "bin": {