Skip to content

feat(design): P-4PT spacing ratchet contract + P-TEXT orphan tier cleanup - #459

Merged
jackwener merged 1 commit into
mainfrom
design/4pt-ratchet-and-text-tiers
Jul 3, 2026
Merged

feat(design): P-4PT spacing ratchet contract + P-TEXT orphan tier cleanup#459
jackwener merged 1 commit into
mainfrom
design/4pt-ratchet-and-text-tiers

Conversation

@jackwener

@jackwener jackwener commented Jul 3, 2026

Copy link
Copy Markdown
Member

Roadmap queue items 5–6（决策 D1：4pt 网格渐进迁移）。

P-4PT — spacing ratchet 契约

新契约 spacing-4pt-ratchet-contract.test.ts：扫描 renderer CSS 的 padding/gap/margin px 值做 4pt 网格检查（0 允许，1px/2px hairline 豁免）。442 个存量违例按文件冻结、只减不增；新文件零容忍；slack 检查防 baseline 生锈（文件改善后必须下调基线）。

P-TEXT — 孤儿档清理（首轮）

--foreground-20/-30 是夹在 surface wash（2..10）与真实文字阶梯（40..80）之间的孤儿档（全仓 8 处调用）：

  • onboarding 分组计数文字 30 → 40（兼修对比度：30% 墨量过不了 4.5:1 硬线）
  • chat.tsx 状态点 30 → 40
  • resize 把手 / bot 状态点 / context-plus 边框：装饰性一次用途 → 内联 color-mix
  • 档位定义 + @theme 桥删除；design-tokens story 阶梯同步（20 → 50）

验证

npm --workspace @maka/desktop test: 1687/1687（新增 2 个 ratchet 测试）

@jackwener
feat(design): P-4PT spacing ratchet contract + P-TEXT orphan tier cle…
39e2d54 
…anup

Queue items 5-6 of docs/design-refinement-roadmap-2026-07.md
(owner decision D1: 4pt grid, incremental migration).

P-4PT: new spacing-4pt-ratchet-contract.test.ts scans renderer CSS
padding/gap/margin px values for 4pt-grid compliance (0 allowed,
1px/2px hairline exempt). The 442 legacy off-grid values are frozen
per file and may only shrink; new files are born clean; a slack check
keeps baselines honest so the ratchet cannot rust.

P-TEXT (first pass): the -20/-30 foreground tiers were orphans (8 call
sites) sitting between the surface washes (2..10) and the real text
ladder (40..80):
- onboarding group count text 30 -> 40 (also a contrast fix: 30% ink
  fails the 4.5:1 line)
- chat.tsx status dots 30 -> 40
- resize handle / bot status dot / context-plus border: inlined their
  color-mix (decorative one-offs, not text tiers)
- tier definitions + @theme bridge removed; design-tokens story scale
  updated (20 -> 50 so the displayed ladder matches the real one)

Desktop suite 1687/1687 (adds 2 ratchet tests).
@jackwener
jackwener merged commit 9689ca1 into main Jul 3, 2026
@jackwener
jackwener deleted the design/4pt-ratchet-and-text-tiers branch July 3, 2026 07:48
@jackwener jackwener mentioned this pull request Jul 3, 2026
Merged
jackwener added a commit that referenced this pull request Jul 3, 2026
@jackwener
docs(design): mark refinement queue round 1 complete (P-SHADOW..P-STA…
10333fa 
…TE) (#460)

All eight queue items resolved across #457/#458/#459: four landed as
code (shadow recipes + dark collapse, input inset step-down,
concentric radii, 4pt ratchet + text tier cleanup) and four audited
as already-compliant or covered (motion durations, dark semantics,
state coverage). Records next-round candidates.
jackwener added a commit that referenced this pull request Jul 3, 2026
@jackwener
test(contract): retire 4pt ratchet in favor of the spacing-converge ban
bdd4ecb 
The ratchet (#459) froze 442 legacy off-grid px values per file as a
transitional mechanism. This PR replaces bare px spacing wholesale
with the --space-* scale and bans new bare px outright
(spacing-converge-contract), which strictly supersedes the ratchet:
after the conversion the ratchet baselines are all stale-high and its
anti-rust slack check would fail. One mechanism, the stronger one.
jackwener added a commit that referenced this pull request Jul 3, 2026
@Astro-Han @jackwener
refactor(ui): converge spacing to --space-* scale, ban bare px (#430 …
4b3858b 
…PR3) (#448)

* fix(ui): --spacing 3.75px bug -> 4px ruler + define --space-* scale (#430 PR3)

The --spacing token was 0.25rem, which under the 15px root font-size
equals 3.75px, not the 4px the comment claimed. This silently broke
alignment between Tailwind's spacing scale (p-2 = 7.5px) and hand-written
px (padding: 8px) — two unrelated scales.

Fix the ruler to absolute 4px in both :root and @theme inline so Tailwind
utilities (p-N, gap-N, m-N) and hand-written var(--space-N) share one
source. Define a 14-value scale covering the codebase's real spacing
distribution: 0/2/4/6/8/10/12 below 16 (even numbers, dense UI needs the
6 and 10 half-steps), 16/20/24/32/40/48/64 at and above (pure 4px
multiples). 1px stays a literal (hairline). Deliberately absent: 14/18/
22/26/28/30/34/36/52/56 — snapped to the nearest scale value in the
follow-up commits to kill magic numbers.

Per the #430 adversarial review, spacing has no single-property anchor
like border-radius, so the upcoming contract scopes to padding/margin/
gap only (not width/height/inset/grid).

* refactor(ui): replace all bare px spacing with var(--space-*) tokens (#430 PR3)

Replace every bare px value in padding/gap/margin across renderer CSS
(689 sites) and TSX arbitrary spacing utilities (125 sites) with
var(--space-*) tokens or Tailwind scale utilities. Snap non-scale values
to the nearest scale tier: 3->2, 5->4, 7->6, 9->8, 11->12, 14->12,
18->16, 22->24, 26->24, 28->24, 30->32, 34->32, 36->40, 52->48, 56->64,
72->64. Negative margins use calc(var(--space-N) * -1). 1px stays a
literal (hairline). Responsive clamp()/max() bounds stay literal (they
are viewport parameters, not spacing beats).

Update 6 contract tests that pinned the old bare-px literals to expect
the new var(--space-*) or scale-utility forms. The chat-header inset
contract's pxDeclaration helper now resolves var(--space-*) tokens to
their px equivalents so the geometric invariant (buttons x width + gaps
+ clearance = inset) still holds.

* test(contract): spacing-converge-contract bans bare px in padding/gap/margin (#430 PR3)

Lock the spacing vocabulary so future PRs can't drift back to ad-hoc
px values. The contract enforces:

1. CSS padding/margin/gap must use var(--space-*), calc(var(--spacing)
   or var(--space-N)), or literals (0/auto/inherit/1px hairline). Bare
   Npx is banned. Responsive clamp()/max()/min() bounds are exempt
   (viewport parameters, not spacing beats).

2. --spacing is 4px (absolute, not 0.25rem) and --space-* tokens are
   pinned to calc(var(--spacing) * N) with the correct multipliers.

3. The @theme inline bridge exports --spacing: 4px so Tailwind p-N/
   gap-N/m-N share the ruler with hand-written var(--space-N).

4. TSX has no arbitrary p-[Npx]/gap-[Npx]/m-[Npx] (except 1px hairline).

Spacing has no single-property anchor like border-radius (adversarial
review in #430), so the contract scopes to padding/margin/gap only.

Also fixes 3 single-line declarations the batch replacement missed
(margin: 2px 0, padding: 16px 20px, margin-top: 2px in single-line
multi-declaration rules).

* docs: refresh design-system §1.5 spacing for --space-* scale (#430 PR3)

* refactor(storybook): redesign Spacing story for --space-* scale (#430 PR3)

Old story showed 6 arbitrary calc(var(--spacing) * N) steps with a
stale 0.25rem comment and a step*4px label that was silently wrong
(--spacing was 3.75px, not 4px). Redesign to show the full 14-value
--space-* scale with token name, pixel value, visual bar, and usage.
Add a 1px hairline section and keep the layout-geometry section.

* test(contract): retire 4pt ratchet in favor of the spacing-converge ban

The ratchet (#459) froze 442 legacy off-grid px values per file as a
transitional mechanism. This PR replaces bare px spacing wholesale
with the --space-* scale and bans new bare px outright
(spacing-converge-contract), which strictly supersedes the ratchet:
after the conversion the ratchet baselines are all stale-high and its
anti-rust slack check would fail. One mechanism, the stronger one.

---------

Co-authored-by: jackwener <jakevingoo@gmail.com>
This was referenced Jul 3, 2026
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jackwener