Bind palette colours exactly: painted shades get their own tokens, slots by painted weight (#3043)

[chubes4]

Summary

DesignSystem::palette() still picks base, contrast, primary and secondary as before. Every other painted colour now competes for the remaining slots on its own painted weight, heaviest first, whatever group it belongs to. Grouping only names roles and breaks ties (a group's own colour before a near shade, then the heavier group). Colours past the 12-colour cap are the lightest painted ones and are reported in literal_colors. A heavily painted near shade of base (e.g. white cards) now gets an exact token instead of losing its slot to a colour painted on one tiny element. The real reporting-site import was not re-run here, so its restyle_coverage and no_matching_token figures are unconfirmed.

What changed

• php-transformer/src/WordPressSitePlan/DesignSystem.php: palette() fills the slots left after the roles with painted colours ranked by their own prominence. Ties go to a group's own colour first, then the heavier group, then the value. Removed the step that gave every group's heaviest colour a slot first. Updated the class comment and the consolidateColors comment.
• php-transformer/tests/fixtures/design-system/heavy-near-shade-tiny-accents.php: new fixture with #ffffff cards on a #f7fafc base, 11 distinct colours, and #34d399/#80a690 each painted on one tiny element.
• php-transformer/tests/unit/design-system-usage-derivation.php: new heavy-near-shade-tiny-accents assertions. The full palette, the #ffffff token, literal_colors == [#34d399, #80a690] and all 8 cards bound to white are checked; these fail on the previous head and pass now.
• php-transformer/tests/unit/design-system-usage-derivation.php: rewrote three near-duplicate-neutrals-small-accent assertions that checked the old behaviour (grey near-duplicates literal, every distinct colour in a slot). They now check that the cyan accent keeps a token, that the one-off amber and rose headings are among the 6 literal colours, and that each grey binds to its exact token or keeps its literal colour. The --cyan custom-property check is unchanged.
• php-transformer/docs/wordpress-site-plan.md: documents the slot-allocation rule.

How to test

1. Run cd php-transformer && composer install --no-interaction --prefer-dist --no-progress && composer test:canonical; expect passes as recorded by Cook's deterministic gate.

Compatibility

Palette contents and accent-N order change for sites with more than 12 painted colours: heavy near shades now take slots ahead of barely used distinct colours, and accent-N follows each colour's own painted weight. Bindings are still exact-value only, so a binding never changes a painted colour. No API or schema changes.

Evidence

• Verified command cd php-transformer && composer install --no-interaction --prefer-dist --no-progress && composer test:canonical: status=succeeded; candidate commit ac3421d70a88b207dbd8f0e2a337379f484d3f14, tree 6e29831fc602f437571a9cb2b1b6a6ede475c508, fingerprint 648d90a7d638f1797c9232a672f2d1a55d5a30ac06bafd51c1485b54c00c3708; durable gate gate-1
• Base unchanged since verification: trunk remains at 811beaa.
• CI expected: Homeboy CI after push
• Candidate adoption provenance: the candidate was promoted from the recorded Cook task execution.
• Cook deterministic verification: 1 gate(s) completed green.
• Durable run execution: Succeeded
• Reviewer-resolvable evidence from source_refs[0]: Bind palette colours exactly: painted shades get their own tokens, slots by painted weight (#3043) #3048
• Task objective: Continue PR Bind palette colours exactly: painted shades get their own tokens, slots by painted weight (#3043) #3048 (issue Absorbed palette shades stay literal: colorSlug binds only a token's exact value #3043) in this worktree. The exact-paint rule is right and CI (including the Docker browser pixel test) is green, but slot allocation defeats the purpose on the real site.
• Verified candidate scope: 4 changed file(s): php-transformer/docs/wordpress-site-plan.md, php-transformer/src/WordPressSitePlan/DesignSystem.php, php-transformer/tests/fixtures/design-system/heavy-near-shade-tiny-accents.php, php-transformer/tests/unit/design-system-usage-derivation.php.
• Verified finalization base: trunk at 811beaa
• deterministic gate passed: sh -c cd php-transformer && composer install --no-interaction --prefer-dist --no-progress && composer test:canonical (Passed)

AI assistance

• AI assistance: Yes
• Tool(s): Homeboy (pi)
• Model: anthropic-claude-opus-5-5
• Used for: [operator-only reference omitted]