Add production readiness checklist v3 with implementation decisions

[jackgranatowski]

Summary

This PR introduces audits/completion-checklist-v3.md, a comprehensive production readiness audit that supersedes v2. Unlike v2 (which was an inventory), v3 is implementation-ready: it documents decisions made after auditing the codebase against the checklist, specifies exact changes needed, lists deliberate rejections, and provides a roadmap to v1.0.

Key Changes

• Decision Log (§A): 10 finalized decisions with exact code changes:

  • D1: Clarify base layer scope (universal, not opinionated) — documentation only
  • D2: Wire behaviour tokens in base (--sf-h1-font-weight, text-wrap, strong-weight, em-style)
  • D3: Implement --sf-contrast-bias as a global text-contrast knob
  • D4: Consume --sf-print-base-size in print.css
  • D5: Introduce tiered bundle scheme (essential, optimal, optimal-components, optimal-utilities, full) and ship forms
  • D6: Integrate form validation states with --sf-field-border-color
  • D7: Fix button :hover bug (misuse of surface-hover token)
  • D8: Add required-field asterisk in forms using :has() + :required
  • D9: Explicit rejections (animation utility classes, 7th brand color, switch toggle, helper text) with rationale
  • D10: Defer minified bundles and cross-browser CI to v0.3 (infrastructure workstream)

• Verification Results (§B): Line-by-line audit against source confirming:

  • Existing tooling (stylelint, CI, commitlint, git hooks) now credited
  • Three stub files (optional/components.css, optional/utilities.css, optional/tokens.components.css) inventoried
  • slashed.forms layer confirmed in 14-layer cascade but missing from README and architecture.md docs

• Outstanding Items (§C): Complete carryover from v2 with status updates and decision tags linking to §A

• Deliberate Rejections (§D9): Rationale for NOT implementing animation utility classes, accent color, switch toggle, helper text, color partials, gradient variants, and pre-compiled themes

• Re-scored Summary (§E): Base layer re-scored 77% → 90% (widgets reclassified as out-of-scope by design); Build re-scored 50% → 70% (existing infra credited); overall 72% → ~78% production-ready

• Roadmap (§F): Three-phase execution plan:

  • v0.2: Foundation polish (D1–D8, bundle scheme, divider tokens, sr-only-focusable)
  • v0.3: Build & test infrastructure (minification, cross-browser CI, axe-core, file/range inputs)
  • v0.4: Documentation sprint (theming guide, browser matrix, token reference, state docs)
  • v1.0: Release gate with explicit criteria

Notable Implementation Details

• All decisions include exact CSS/config changes (not just descriptions)
• Regression guard documented for D2 (strong-weight token default fix required before wiring)
• Bundle scheme uses @layer ordering (physical concatenation order irrelevant)
• Philosophy preserved: no build-step requirement for consumers; no utility-first drift; BEM-first identity maintained
• Documentation gaps (theming guide, browser support, token reference) identified as the v1.0 gating item

This document is not yet implemented — it is the instruction set for implementation.

https://claude.ai/code/session_01AsRUmGk1efwLcreDfQvXNZ

Summary by CodeRabbit

• Documentation
  • Added v3 of the Production Readiness Checklist (2026-05-21) with a formal decision log detailing prioritized UI/visual adjustments, verification results, outstanding items, recommended holds/removals, a rescored summary, and an ordered execution roadmap through v1.0 with gating milestones and next-release priorities.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 29f07aa2-4b5c-4f38-8443-f989561cd3fd

📥 Commits

Reviewing files that changed from the base of the PR and between 5c954e0 and 58c5746.

📒 Files selected for processing (1)

• audits/completion-checklist-v3.md

✅ Files skipped from review due to trivial changes (1)

• audits/completion-checklist-v3.md

---

📝 Walkthrough

Walkthrough

This PR adds audits/completion-checklist-v3.md, a new Production Readiness Checklist dated 2026-05-21 that documents implementation-ready CSS/token changes (D1–D10), verification results against source, outstanding work inventory across 16 categories, recommendations for excess items, rescored summaries by layer, and a phased execution roadmap through v1.0 with documented dependencies.

Changes

Production Readiness Checklist v3 Update

Layer / File(s)	Summary
Scope and implementation-ready decisions audits/completion-checklist-v3.md	Document header establishes v3 as implementation-ready and introduces the formal decision log (§A) with D1–D10 directives for CSS/token file changes: base-layer scope, token wiring into core files, --sf-contrast-bias implementation, --sf-print-base-size consumption, slashed.forms distribution fixes, --sf-field-border-color wiring, primary button :hover correction, and required-field asterisk using classless :has() patterns.
Verification results and outstanding work inventory audits/completion-checklist-v3.md	Verification table (§B) maps v2 claims to confirmed/newly found statuses; outstanding items matrix (§C) enumerates carryover work across 16 categories including tokens, reset, base, forms, layout, states, themes, motion, accessibility, print, legacy, build/distribution, tests, documentation, internal consistency, and newly documented stub files.
Summary, recommendations, and execution roadmap audits/completion-checklist-v3.md	Excess section (§D) recommends removals and holds; rescored summary tables (§E) update production-ready percentages by layer; execution roadmap (§F) sequences v0.2–v1.0 milestones with v0.3 build/test and v0.4 documentation gating.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• codeslash-dev/SLASHED#51: Directly related prior checklist update moving from v2 to v3 checklist structure and status expansion.
• codeslash-dev/SLASHED#47: Related audit documentation update in the same completion checklist series, providing earlier checklist baseline.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately describes the main change: adding a new production readiness checklist (v3) that documents implementation decisions for the project.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/completion-checklist-v2-review-hmDhv

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

audits/completion-checklist-v3.md (1)

89-134: 💤 Low value

Consider expanding the ellipsis notation for implementation clarity.

Lines 123-124 use "…h2–h6 identically…" as shorthand. While the pattern is clear (add font-weight: var(--sf-hN-font-weight) to each heading), an implementer might appreciate seeing the complete diff for at least one more heading (h2) to eliminate ambiguity. The regression guard for --sf-body-strong-weight is excellent.

📝 Optional: show h2 explicitly

 h1 { font-size: var(--sf-h1-size); line-height: var(--sf-h1-line-height); font-weight: var(--sf-h1-font-weight); letter-spacing: var(--sf-h1-letter-spacing); }
+h2 { font-size: var(--sf-h2-size); line-height: var(--sf-h2-line-height); font-weight: var(--sf-h2-font-weight); letter-spacing: var(--sf-h2-letter-spacing); }
+/* h3–h6 follow the same pattern */

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@audits/completion-checklist-v3.md` around lines 89 - 134, The diff uses an
ellipsis ("…h2–h6 identically…") which may cause ambiguity; update core/base.css
to show at least one additional explicit heading rule (e.g., the h2 rule)
mirroring the h1 pattern so implementers see the exact format to apply (include
font-weight: var(--sf-h2-font-weight), size/line-height vars and
letter-spacing), and ensure core/tokens.css has the adjusted default for
--sf-body-strong-weight set to var(--sf-font-weight-bold) so b/strong map to
700; reference the h1/h2 rules, --sf-hN-font-weight tokens, and
--sf-body-strong-weight when making the changes.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@audits/completion-checklist-v3.md`:
- Around line 89-134: The diff uses an ellipsis ("…h2–h6 identically…") which
may cause ambiguity; update core/base.css to show at least one additional
explicit heading rule (e.g., the h2 rule) mirroring the h1 pattern so
implementers see the exact format to apply (include font-weight:
var(--sf-h2-font-weight), size/line-height vars and letter-spacing), and ensure
core/tokens.css has the adjusted default for --sf-body-strong-weight set to
var(--sf-font-weight-bold) so b/strong map to 700; reference the h1/h2 rules,
--sf-hN-font-weight tokens, and --sf-body-strong-weight when making the changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5a2522f6-0daa-49f1-9279-c331774393ba

📥 Commits

Reviewing files that changed from the base of the PR and between 965672d and 5c954e0.

📒 Files selected for processing (1)

• audits/completion-checklist-v3.md