feat(tokens): API freeze - new tokens, hardcode fixes, cleanup

[kiro-agent]

This pull request was created by @kiro-agent on behalf of @jackgranatowski 👻

Comment with /kiro fix to address specific feedback or /kiro all to address everything.
_{Learn about Kiro autonomous agent}

---

Summary

Prepares the token layer for API freeze by:

• Adding missing tokens identified in audits Add comprehensive public API audit for SLASHED v0.3.0 #94, docs: pre-freeze API audit (audit-b) for v0.3.0 #95, docs(audit): pre-freeze API audit for v0.3.0 #96
• Replacing hardcoded values with token references
• Removing dead audit references
• Fixing the .sf-frame--4-3 bug (was rendering 3:2)

New tokens (12)

Token	File	Purpose
--sf-animation-spin	tokens.css	Preset for spinner (.is-loading)
--sf-animation-shimmer	tokens.css	Preset for skeleton (.is-skeleton)
--sf-state-pending-opacity	tokens.css	Semantic opacity for .is-pending
--sf-ratio-4-3	tokens.css	Replaces ambiguous --sf-ratio-photo
--sf-ratio-3-2	tokens.css	Explicit 3:2 ratio token
--sf-color-primary--hover	tokens.css	Brand hover (darkened)
--sf-color-secondary--hover	tokens.css	Brand hover
--sf-color-tertiary--hover	tokens.css	Brand hover
--sf-color-action--hover	tokens.css	Brand hover
--sf-color-neutral--hover	tokens.css	Brand hover
--sf-alternate-gap	tokens.layout.css	Per-primitive gap for .sf-alternate
--sf-alternate-inner-gap	tokens.layout.css	Inner gap for .sf-alternate children

@Property registrations (4)

--sf-is-active, --sf-is-current, --sf-is-pressed, --sf-is-open - formalizes state flag pattern (matches existing --sf-is-dark).

Hardcode fixes (10 replacements)

• states.css: opacity 0.7/0.5 → tokens, inline animations → preset tokens
• accessibility.css: z-index: 9999 → var(--sf-z-max), 2px → var(--sf-border-width-2)
• layout.css: .sf-frame--4-3/--3-2 → ratio tokens, .sf-alternate → gap tokens
• reset.css / base.css: removed mismatched 3.5rem fallbacks from --sf-header-height
• forms.css: inline oklch hover → var(--sf-color-action-hover, var(--sf-color-action--hover))
• tokens.css: --sf-animation-blink now respects --sf-motion-scale

Other fixes

• Removed 3 dead references to deleted audits/ directory
• Fixed alias chain comment: "≤2 hops" → "≤3 hops" with explanation
• Deprecated --sf-ratio-photo (removal in 0.5.0)

Tested

• npm run build - all 19 dist bundles regenerated
• Lint clean

[jackgranatowski]

PR #104 Review — feat(tokens): API freeze — new tokens, hardcode fixes, cleanup

🚨 CI is failing — cannot merge until fixed

Two required checks are failing on this PR:

Check	Status
Build bundle	✅
Lint CSS	✅
Regression tests	❌
Verify generated docs	❌

Fix needed for "Verify generated docs": 12 new tokens were added to core/tokens.css / core/tokens.layout.css but docs/tokens.md was not regenerated. Run npm run docs:tokens and commit the updated file. This is the same pattern the repo enforces via CI.

Fix needed for "Regression tests": The Playwright test suite is failing. The most likely cause is the removal of the 3.5rem fallback from --sf-header-height in base.css and reset.css:

-  scroll-padding-top: var(--sf-header-height, 3.5rem);
+  scroll-padding-top: var(--sf-header-height);

If the test harness loads the CSS without a WordPress environment (where --sf-header-height is always defined), the token resolves to its initial value (0 for a length with no initial-value set, or nothing if @property isn't registered). This could cause scroll offset assertions to fail. The 3.5rem fallback may have been load-bearing in tests. Check whether the regression suite defines --sf-header-height in its test fixture.

---

✅ Code quality — the changes themselves look good

New tokens:

• --sf-animation-spin / --sf-animation-shimmer preset tokens clean up states.css nicely — removing the repeated sf-spin var(--sf-duration-slower) linear infinite inline and centralising it in tokens.css is the right pattern.
• --sf-state-pending-opacity: 0.7 / --sf-opacity-50 replacements are correct tokenisation.
• --sf-ratio-4-3 / --sf-ratio-3-2 fix: the old .sf-frame--4-3 was pointing at --sf-ratio-photo which was 3 / 2 — so 4:3 frames were actually rendering at 3:2. This is a real bug fix.
• @property registrations for --sf-is-active, --sf-is-current, --sf-is-pressed, --sf-is-open follow the --sf-is-dark pattern correctly.
• Brand hover tokens (--sf-color-primary--hover etc.) using relative oklch(from ... calc(l - 0.05) c h) is the right approach — the -- double-hyphen modifier naming convention is consistent with the existing palette naming.

Hardcode replacements:

• z-index: 9999 → var(--sf-z-max) in accessibility.css is correct.
• border-block-start-width: 2px → var(--sf-border-width-2) in the print rule is correct.
• opacity: 0.5 → var(--sf-opacity-50) on .is-dragging is correct.

Alias graph comment:

• The "≤2 hops → ≤3 hops" correction is accurate — --sf-cluster-gap → --sf-space-gap → --sf-gap is indeed 3 levels. The example text added makes this concrete.

--sf-animation-blink change:

• Now respects --sf-motion-scale, which is correct for motion-sensitive users.

---

Summary

The code changes are solid and the bug fix (.sf-frame--4-3) is a genuine correctness improvement. The PR cannot merge in its current state because of the two CI failures. Fix:

1. Run npm run docs:tokens and commit docs/tokens.md
2. Investigate the Playwright failure — likely the --sf-header-height fallback removal or a visual snapshot breaking due to the .sf-frame--4-3 / .sf-frame--3-2 ratio fix

Verdict: COMMENT — approve the code changes, but CI must pass before this can merge.

---

Generated by Claude Code