docs(LINCHPIN-5253): Document the Linchpin slug vocabulary and correct the paint-name claim - #13
Merged
Merged
Conversation
…t the paint-name claim Measuring slug usage across the 265 pattern and part files in themes/linchpin showed the vocabulary problem is much narrower than assumed, and that what I wrote in #10 was wrong. Of 1,813 slug references, 96% already flow through Ollie's structural core - base 557, primary 277, border-light 236, main-accent 203, secondary 178, main 143. The paint tail is 73 references, about 4%. So base-wp-theme-2026 did not replace the vocabulary; it kept the structural core and appended paint names alongside it. The precedents reference said themes/linchpin was "still paint-named", which overstates it. Corrected. wp-design-tokens now names the structural slugs to reach for, lists the paint names to avoid in new work, and flags that accent means different colours in themes/linchpin and themes/docspress-linchpin, so it can never be assumed. Also records why the tail cannot simply be retired. No two slugs in the palette share a value, so every remap is a visual change rather than a rename, and removing a slug stops WordPress emitting its preset custom property, which silently breaks saved post content carrying has-slug-background-color. That work needs a live content audit and design sign-off. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…roject skill
Applying the placement test to what PR 928 added to linchpin-theme-conventions:
some of it is true on any project and belongs here, not in one repo's file.
Moved up, because they hold regardless of whose brand it is:
- measure every state, not just the resting one. A resting state that passes
tells you nothing about hover, and auditing only rest states is how a button
ships that is accessible only while being clicked
- interaction ramp direction follows the label colour - light surface with a
dark label lightens, dark surface with a white label darkens. Get this
backwards and no amount of tuning the resting colour fixes it
- disabled controls are exempt under WCAG SC 1.4.3, and a 16px bold button
label is not large text, so 4.5:1 applies rather than 3:1
Stays in linchpin.com because it is one brand's decision: the specific teal, the
hex values and ratios, and the ghost-button gap.
Also removes a stale entry that should never have been in a portable skill - the
2.15:1 button contract was recorded here as an open question, and PR 928 decided
it. Project-specific open items do not belong in the library layer; the durable
lesson does.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of LINCHPIN-5253.
What measuring changed
I counted slug usage across the 265 pattern and part files in
themes/linchpinbefore touching anything. The result reframes the ticket and corrects something I got wrong in #10.Of 1,813 slug references:
base557,primary277,border-light236,main-accent203,secondary178,main143, + tintstrue-black35,white-2511,green5,gray4,medium-gray4,warm4,black-104,yellow2,accent2,almost-black2So
base-wp-theme-2026didn't throw Ollie's vocabulary away — it kept the structural core and appended paint names alongside. My line intheme-baseline-precedents.mdcallingthemes/linchpin"23, still paint-named" overstates it. Corrected here.Why the tail can't just be retired
This is the part worth reading before anyone plans the migration:
true-black #000000→main #031e1e,gray #BBBBBB→medium-gray #8e949a,warm #F5F2EC→base #ffffff— is a visual change, not a rename.--wp--preset--color--<slug>, so saved posts carryinghas-<slug>-background-colorlose their colour silently.That makes retirement design work gated on a content audit, not a find-and-replace. Recorded in the skill rather than attempted.
Change
wp-design-tokens— names the structural slugs to reach for, the paint names to avoid in new work, and the fact thataccentmeans different colours in the two themes (purple#7D58C6vs teal#3fc1d0), so it can never be assumed.theme-baseline-precedents.md— corrected claim, with the measured numbers.Still open on the ticket
The Done criterion "themes/linchpin exposes role-named aliases" is not met here — aliasing means adding duplicate slugs, which the chosen approach deliberately avoided, and retiring the tail needs the audit above. Flagged for a follow-up rather than half-done.
Verify
npm run validate --strict→ 22 skills, 0 errors, 0 warnings.🤖 Generated with Claude Code