feat(design): port 2026-07 handoff — z/breakpoint tokens, type rebase, seven new component cards

[altaywtf]

Summary

Ports the July 2026 round from the putio-design-system Claude Design project (handoffs/handoff-2026-07.md) into the repo's own token pipeline and preview guide, and updates the repo-local design-handoff skill with the new project-based import flow. Project-side regressions (dropped a11y attributes, a reintroduced #F3C437 hover caption, a flattened solid-foreground) were kept out and relayed back to the design project as feedback.

Changed

• tokens/ — new z scale (--z-dropdown…--z-tooltip, 1000–1500) and breakpoint group (640/768/1280px); --shadow aliases --shadow-color in both modes; root font-size 14px → 15px at ≥ --bp-lg; type scale rebased to production (--fs-base 1rem, fixed 48/64/96px display tiers, --fs-4xl removed — no consumers); button default/info promoted from foundation.css live aliases to mode-scoped DTCG tokens; reduced-motion block. 313 → 330 tokens; dist/* + system/tokens.css regenerated.
• system/preview/ — seven new cards (menu, data table, web player, task progress, folder picker, segmented control, skeleton) with a11y hardening applied on import; tv-shell.css fully scoped under .tv; web-shell layout fixes; APCA contrast-contract copy + data-contrast-contract tags; href="#" sweeps.
• system/design-system.html — seven new embeds, rebased type-ramp rows.
• DESIGN.md / system/README.md — front-matter follows the new scale (contract-checked); README gains shadcn/Base UI interop table (all aliases verified to exist), z/breakpoint/root-size and theme-system guidance.
• .agents/skills/putio-design-handoff/ — DesignSync project import flow, @dsCard handling, regeneration-regression audit step, expanded contract checklist.

Risks

• The type-scale rebase changes rendered sizes everywhere --fs-* is consumed (body 13.1px → 14–15px, buttons to 0.875rem); previews were re-verified visually via the axe/render suite, but downstream consumers of @putdotio/design will see the new values on next upgrade.
• --fs-4xl is removed from the public token surface — a breaking removal for any external consumer that referenced it (none found in this repo).
• --button-info-fg/--button-default-* moved from :root live aliases to generated mode-scoped tokens; rendering is equivalent, but the resolution mechanism changed.

Verification

• pnpm verify:full green: typecheck, token build + drift check, design-system contract checks, html-validate, static smoke, 140 Playwright render + axe tests (up from 119; both themes, 3:1 floor), npm pack --dry-run.
• An adversarial multi-agent review of the diff surfaced six defects (ported focus-halo regression, an APCA-contract violation in the mobile swipe actions, a flex text-overflow recipe that couldn't ellipsize, one missed href, a stale comment, a sample-size drift) — all fixed before this PR and re-verified.

Complexity

Neutral — new tokens and cards follow the existing pipeline and conventions; no new build steps or dependencies.

🤖 Generated with Claude Code

---

Summary by cubic

Ports the July 2026 design handoff into our token pipeline and preview guide, aligning type, z/breakpoints, and button tokens with production. Adds seven new preview cards and a Design project token-mirror exporter; tokens in tokens/**/*.tokens.json remain the source of truth.

• New Features

  • Tokens: z/breakpoint scales, reduced-motion block, --shadow aliases --shadow-color, responsive root-size (14px → 15px at --bp-lg), type rebase (--fs-base 1rem; display tiers 48/64/96; --fs-4xl removed), button default/info promoted to mode-scoped tokens. 313 → 330.
  • Previews: new cards — menu, data table, web player, task progress, folder picker, segmented control, skeleton; APCA contract tags; href="#" sweeps; .tv scoping for tv-shell.css; web-shell layout fixes.
  • Docs: DESIGN.md and system/README.md updated with the new scale, font hosting, z/breakpoint guidance, and interop notes.
  • Design handoff skill: DesignSync project import flow, @dsCard handling, regeneration-regression audit, and token governance recorded (design mirrors built values; proposals land here).
  • Exporter: new scripts/export-design-mirror.ts and pnpm design:mirror to emit the design project’s tokens.json, annotated tokens.css, and tokens.base.css from repo builds into tmp/design-mirror/ for DesignSync push.

• Migration

  • Type scale changed: body is --fs-base 1rem (renders 14–15px); buttons use --fs-sm 0.875rem. Audit any UI tied to --fs-*.
  • --fs-4xl was removed; switch to --fs-2xl (48px) or --fs-3xl (64px).
  • Button default/info colors moved from :root aliases to mode-scoped tokens. Update any direct references to old aliases.

^{Written for commit 32b6dfe. Summary will update on new commits.}

[Copilot]

Pull request overview

Ports the July 2026 design handoff into this repo’s token pipeline and preview system, updating the public token surface (type scale, z-index scale, breakpoints, button role tokens) and expanding the preview/specimen set to cover additional UI patterns.

Changes:

• Rebases typography tokens and foundation styles (responsive root size, fixed display tiers) and adds new global z.* and breakpoint.* tokens.
• Promotes button default/info role tokens into the DTCG pipeline (mode-scoped), regenerating dist/* + CSS outputs.
• Adds/updates multiple preview cards and docs, including new embeds in system/design-system.html and updated handoff automation guidance.

Reviewed changes

Copilot reviewed 27 out of 33 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tokens/semantic.tokens.json	Makes surface.dark.shadow a compat alias to surface.dark.shadowColor.
tokens/primitives.tokens.json	Rebases font sizes, removes fs-4xl, and adds z + breakpoint token groups; aliases shadow color.
tokens/foundation.css	Updates semantic type mapping, adds responsive root font-size step, removes live button aliases, adds reduced-motion rules.
tokens/components.tokens.json	Adds mode-scoped DTCG tokens for button.info.* and button.default.*.
system/tokens.css	Regenerated token CSS and foundation styles with new type/z/breakpoint/button tokens and reduced-motion block.
system/README.md	Expands docs for fonts, z/breakpoint/root sizing rules, theme system, and shadcn/Base UI interop guidance.
system/preview/web-shell.html	Layout tweaks for truncation and grid spacing; makes search responsive.
system/preview/tv-shell.css	Scopes TV shell CSS under .tv and constrains page-level background styling.
system/preview/components-task-progress.html	New preview card for task progress + progress primitives with ARIA progressbar usage.
system/preview/components-table.html	New preview card for data table + selection toolbar (uses --z-sticky).
system/preview/components-skeleton.html	New preview card documenting skeleton/shimmer behavior with reduced-motion considerations.
system/preview/components-segmented-control.html	New preview card for segmented control with role="radiogroup" + aria-checked contract.
system/preview/components-player-web.html	New preview card for web player chrome and menu/buffering states.
system/preview/components-notification.html	Replaces empty href="" anchors with href="#" in specimens.
system/preview/components-menu.html	New preview card for menu/context menu/submenu surface recipe and roles.
system/preview/components-form-layouts.html	Replaces empty href="" anchors with href="#" across auth/settings specimens.
system/preview/components-form-fields.html	Replaces empty href="" anchors with href="#" in error summary specimen.
system/preview/components-buttons.html	Updates accessibility copy to reflect APCA contrast-contract framing.
system/preview/components-breadcrumbs.html	Replaces empty href="" anchors with href="#".
system/preview/brand-empty-state.html	Replaces empty href="" anchors with href="#".
system/preview/accessibility.html	Adds data-contrast-contract="apca" to specimens and updates type/focus copy; replaces empty href="".
system/preview/_components.css	Rebases default button font-size to --fs-sm and documents APCA tagging contract expectations.
system/design-system.html	Adds embeds for new preview cards and updates type ramp rows to match rebased scale.
dist/tokens.js	Regenerated JS token map for new tokens/aliases and updated typography values.
dist/tokens.flat.json	Regenerated flat token export for new tokens/aliases and updated typography values.
dist/tokens.dtcg.json	Regenerated DTCG export reflecting new button role tokens, aliases, z, breakpoints, and type changes.
dist/tokens.d.ts	Regenerated token-name type union (adds new tokens; removes typography.fontSize.4xl).
dist/figma/putio.tokens.json	Regenerated Figma-friendly token export reflecting the updated token surface and descriptions.
dist/css/tokens.css	Regenerated package CSS tokens + foundation styles with new z/breakpoint/button/type values.
DESIGN.md	Updates typography front-matter sizes and adds explicit notes about responsive root, fixed display tiers, z/breakpoint rules.
.agents/skills/putio-design-handoff/SKILL.md	Updates skill guidance for DesignSync project import flow and audit/checklist expectations.
.agents/skills/putio-design-handoff/references/repo-pipeline.md	Updates prototype→repo mapping notes and fixed-check expectations (type, hover hex, solid-foreground, etc.).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".agents/skills/putio-design-handoff/SKILL.md">

<violation number="1" location=".agents/skills/putio-design-handoff/SKILL.md:72">
P2: The new governance guidance tells the agent to reference `uploads/putio-design-governance-2026-07.md` when writing feedback, but Step 2 (Option A) explicitly tells the agent to skip `uploads/` during project file fetching. An agent following the step-2 skip directive will never have this file available to consult — creating a contradiction between the two instructions.

**Recommendation:** Either add a carve-out in Step 2 to fetch this specific file from `uploads/` (e.g., "...skip `uploads/` except `uploads/putio-design-governance-2026-07.md` if present"), or move the governance reference to a path outside the skipped directories so the agent reliably has it for feedback writing.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The new governance guidance tells the agent to reference uploads/putio-design-governance-2026-07.md when writing feedback, but Step 2 (Option A) explicitly tells the agent to skip uploads/ during project file fetching. An agent following the step-2 skip directive will never have this file available to consult — creating a contradiction between the two instructions.

Recommendation: Either add a carve-out in Step 2 to fetch this specific file from uploads/ (e.g., "...skip uploads/ except uploads/putio-design-governance-2026-07.md if present"), or move the governance reference to a path outside the skipped directories so the agent reliably has it for feedback writing.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .agents/skills/putio-design-handoff/SKILL.md, line 72:

<comment>The new governance guidance tells the agent to reference `uploads/putio-design-governance-2026-07.md` when writing feedback, but Step 2 (Option A) explicitly tells the agent to skip `uploads/` during project file fetching. An agent following the step-2 skip directive will never have this file available to consult — creating a contradiction between the two instructions.

**Recommendation:** Either add a carve-out in Step 2 to fetch this specific file from `uploads/` (e.g., "...skip `uploads/` except `uploads/putio-design-governance-2026-07.md` if present"), or move the governance reference to a path outside the skipped directories so the agent reliably has it for feedback writing.</comment>

<file context>
@@ -69,7 +69,7 @@ rg -n "tokens.json|tokens.base.css|tools/build-tokens|yellow-solid|button-primar
    - New preview cards: strip the `@dsCard` marker, register embeds in `system/design-system.html`, and remember axe runs on every card in both modes (3:1 floor) unless `data-theme-lock` pins one mode.
    - If a Claude prototype value conflicts with `DESIGN.md`, `system/README.md`, or token checks, prefer the repo contract unless the user explicitly asks to change it.
-   - Governance claims in the project (e.g. "this project is the sole authoring layer; the repo's `tokens/` is generated output") are decisions for the maintainer — surface them, don't silently adopt them.
+   - Governance (decided 2026-07): this repo's `tokens/**/*.tokens.json` is the canonical authoring source; the design project is the design layer and mirrors the built values. Token changes in a handoff are proposals until they land here. If the project's docs re-assert authoring-layer status, correct them via feedback (see `uploads/putio-design-governance-2026-07.md` in the project).
 
 6. Verify.
</file context>

[cubic-dev-ai]

3 issues found and verified against the latest diff

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="system/README.md">

<violation number="1" location="system/README.md:144">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

The README makes specific implementation claims about `data-slot` and `data-state` usage in `components-modal.html`, `components-folder-picker.html`, and `components-form-layouts.html` that are not present in the codebase. Documentation should not describe patterns that do not exist in the referenced files. Either remove the fabricated claims or implement the described attributes in the corresponding preview cards.</violation>
</file>

<file name="system/preview/components-buttons.html">

<violation number="1" location="system/preview/components-buttons.html:172">
P3: Copy-edit: `APCA Lc 60+ contract` should be `APCA Lc 60+ contrast`. APCA is a contrast algorithm, so 'contrast' is the correct accessibility term here. If `data-contrast-contract` is an intentional portmanteau attribute name, that's fine — but the prose describing the threshold should use standard terminology.</violation>
</file>

<file name="system/preview/components-segmented-control.html">

<violation number="1" location="system/preview/components-segmented-control.html:67">
P2: Focus-visible ring uses a custom double-ring shadow instead of the `--shadow-focus` token. The design system already provides `--shadow-focus` (3px soft yellow halo at 35% alpha) and the focus-system page explicitly says not to invent separate focus styles. Consider switching to `var(--shadow-focus)` for consistent keyboard-focus appearance — or if the double-ring is intentional for small in-tray controls, document the rationale in the CSS comment.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Custom agent: Flag AI Slop and Fabricated Changes

The README makes specific implementation claims about data-slot and data-state usage in components-modal.html, components-folder-picker.html, and components-form-layouts.html that are not present in the codebase. Documentation should not describe patterns that do not exist in the referenced files. Either remove the fabricated claims or implement the described attributes in the corresponding preview cards.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At system/README.md, line 144:

<comment>The README makes specific implementation claims about `data-slot` and `data-state` usage in `components-modal.html`, `components-folder-picker.html`, and `components-form-layouts.html` that are not present in the codebase. Documentation should not describe patterns that do not exist in the referenced files. Either remove the fabricated claims or implement the described attributes in the corresponding preview cards.</comment>

<file context>
@@ -53,24 +71,81 @@ For **TV preview cards**, also load `preview/tv-shell.css` — it adds the `.tv`
+
+### Compound parts via `data-slot`
+
+shadcn marks parts of compound components with `data-slot="card-header"`,
+`data-slot="card-title"`, etc. We do the same on the modal and folder picker
+(`data-slot="modal" / "modal-header" / "modal-body" / "modal-footer"`) and the
</file context>

[cubic-dev-ai]

P2: Focus-visible ring uses a custom double-ring shadow instead of the --shadow-focus token. The design system already provides --shadow-focus (3px soft yellow halo at 35% alpha) and the focus-system page explicitly says not to invent separate focus styles. Consider switching to var(--shadow-focus) for consistent keyboard-focus appearance — or if the double-ring is intentional for small in-tray controls, document the rationale in the CSS comment.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At system/preview/components-segmented-control.html, line 67:

<comment>Focus-visible ring uses a custom double-ring shadow instead of the `--shadow-focus` token. The design system already provides `--shadow-focus` (3px soft yellow halo at 35% alpha) and the focus-system page explicitly says not to invent separate focus styles. Consider switching to `var(--shadow-focus)` for consistent keyboard-focus appearance — or if the double-ring is intentional for small in-tray controls, document the rationale in the CSS comment.</comment>

<file context>
@@ -0,0 +1,124 @@
+    color: var(--text);
+    box-shadow: var(--shadow-sm);
+  }
+  .seg button:focus-visible { box-shadow: 0 0 0 2px var(--yellow-solid), 0 0 0 3.5px var(--text); }
+  .seg.sm { padding: 2px; }
+  .seg.sm button { height: 26px; padding: 0 10px; font-size: var(--fs-xs); }
</file context>

[cubic-dev-ai]

P3: Copy-edit: APCA Lc 60+ contract should be APCA Lc 60+ contrast. APCA is a contrast algorithm, so 'contrast' is the correct accessibility term here. If data-contrast-contract is an intentional portmanteau attribute name, that's fine — but the prose describing the threshold should use standard terminology.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At system/preview/components-buttons.html, line 172:

<comment>Copy-edit: `APCA Lc 60+ contract` should be `APCA Lc 60+ contrast`. APCA is a contrast algorithm, so 'contrast' is the correct accessibility term here. If `data-contrast-contract` is an intentional portmanteau attribute name, that's fine — but the prose describing the threshold should use standard terminology.</comment>

<file context>
@@ -169,7 +169,7 @@
 
   <div class="tip">
-    <b>Accessibility floor.</b> White-on-green and white-on-red sit at 3.2–3.9 contrast — they only pass WCAG as <em>large text</em> (≥14px medium uppercase). <b>Never use <code>btn-sm</code> or <code>btn-xs</code> for <code>btn-success</code>, <code>btn-danger</code>, or <code>btn-info</code>.</b> For tight rows use <code>btn-primary</code> (yellow on black = 14:1 AAA at any size) or <code>btn-default</code>. See the <em>Accessibility audit</em> preview.
+    <b>Accessibility floor.</b> White-on-green and white-on-red sit at 3.2–3.9 contrast — an accepted <b>APCA Lc 60+ contract</b> (medium-weight uppercase labels, tagged <code>data-contrast-contract="apca"</code>), not a WCAG 4.5:1 pass. <b>Never use <code>btn-sm</code> or <code>btn-xs</code> for <code>btn-success</code>, <code>btn-danger</code>, or <code>btn-info</code>.</b> For tight rows use <code>btn-primary</code> (yellow on black = 14:1 AAA at any size) or <code>btn-default</code>. See the <em>Accessibility audit</em> preview.
   </div>
 </div>
</file context>

Suggested change

<b>Accessibility floor.</b> White-on-green and white-on-red sit at 3.2–3.9 contrast — an accepted <b>APCA Lc 60+ contract</b> (medium-weight uppercase labels, tagged <code>data-contrast-contract="apca"</code>), not a WCAG 4.5:1 pass. <b>Never use <code>btn-sm</code> or <code>btn-xs</code> for <code>btn-success</code>, <code>btn-danger</code>, or <code>btn-info</code>.</b> For tight rows use <code>btn-primary</code> (yellow on black = 14:1 AAA at any size) or <code>btn-default</code>. See the <em>Accessibility audit</em> preview.

<b>Accessibility floor.</b> White-on-green and white-on-red sit at 3.2–3.9 contrast — an accepted <b>APCA Lc 60+ contrast</b> (medium-weight uppercase labels, tagged <code>data-contrast-contract="apca"</code>), not a WCAG 4.5:1 pass. <b>Never use <code>btn-sm</code> or <code>btn-xs</code> for <code>btn-success</code>, <code>btn-danger</code>, or <code>btn-info</code>.</b> For tight rows use <code>btn-primary</code> (yellow on black = 14:1 AAA at any size) or <code>btn-default</code>. See the <em>Accessibility audit</em> preview.

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/export-design-mirror.ts">

<violation number="1" location="scripts/export-design-mirror.ts:111">
P3: Dark-mode aliases that reference another mode-scoped token are resolved through that token’s light `$value`, so the exporter can report false dark mismatches and replace valid dark aliases with literals. Consider resolving references in a dark context against `putio.mode.dark` when present.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: Dark-mode aliases that reference another mode-scoped token are resolved through that token’s light $value, so the exporter can report false dark mismatches and replace valid dark aliases with literals. Consider resolving references in a dark context against putio.mode.dark when present.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/export-design-mirror.ts, line 111:

<comment>Dark-mode aliases that reference another mode-scoped token are resolved through that token’s light `$value`, so the exporter can report false dark mismatches and replace valid dark aliases with literals. Consider resolving references in a dark context against `putio.mode.dark` when present.</comment>

<file context>
@@ -0,0 +1,205 @@
+      const [group, key] = refPath.split(".", 2) as [string, string];
+      const node = (template[group] as JsonObject | undefined)?.[key];
+      if (!isToken(node)) throw new Error(`unknown ref {${refPath}}`);
+      return resolveRef(String(node.$value), depth + 1);
+    });
+  };
</file context>