feat(skills): upgrade design-handoff for greenfield + real export bundle#9
Merged
Merged
Conversation
Rework the design-handoff skill to match Claude Design's real .tar.gz "Handoff to Claude Code" bundle and to handle both reconciling into an existing design system and bootstrapping a new one from scratch. - Correct the export assumptions: drop the unverified ?v=N cache-busting, the task export:design/.design/tokens.json pipeline, and bundle screenshots. The bundle is README + chat transcript + prototype HTML/JSX/CSS + tokens.css + uploads, ported (not pasted) into the stack. - Add a greenfield bootstrap path (Tailwind v4 + shadcn init, globals.css, /brand, docs/design, Taskfile tasks) with per-framework recipes: TanStack Router, React Router/plain, and Astro 6 (React islands). - Decompose the monolithic SKILL.md into a lean (~220-line) phased/gated orchestrator plus nine progressive-disclosure references. - Add bundled assets: a zero-dependency OKLCH->WCAG static contrast checker (check-contrast.mjs, tested exit 0/1/2) and Taskfile.design.yml. - Preserve the strong parts: role-based token mapping, the dual contrast gate, the licensing gate, sign-off-before-deletion, and PR-not-merge. Update CLAUDE.md and README.md to reflect greenfield + the new structure. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add an explicit "gather decisions up front" step after ingest/detection so the agent asks everything it needs (e.g. /brand scope) in a single AskUserQuestion batch, letting Phases 1-5 build uninterrupted. Only the Phase 6 sign-off stays late, since it approves the built result. Reframe brand-page.md's scope question as decided during intake. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…andoff Add a responsive-and-cross-browser reference and wire it into the build and verify phases: - Phase 3 now builds mobile-first/responsive (Tailwind breakpoints, fluid layout, dvh, container queries). - Phase 5's verification matrix spans viewports (phone/tablet/desktop) and rendering engines (Chromium/Firefox/WebKit incl. mobile Safari) via Playwright, with the WebKit-approximates-Safari caveat and Playwright vs agent-browser guidance. - Definition of Done gains a responsive + cross-browser line; screenshot step in verification-and-signoff.md expands to the full matrix. Also fix a prettier-wrapped '+' that had turned a sentence into a stray list item in components-and-states.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…tion Rework the default /brand spec from a short bullet list into a comprehensive, automation-friendly reference, since it's the always-on deliverable and may be consumed by tooling: - Foundations: every semantic color token (with oklch + hex + contrast badge), full typography (roles, scale, prose block), spacing/sizing/radius/shadow/ border/opacity/z-index, motion, iconography, breakpoints. - Components & patterns: every component and custom one, across all variants, sizes, and states, grouped by family (actions/forms/feedback/nav/data) so nothing is missed; plus composition patterns. - Brand assets: logo system (variants, clear-space, misuse), favicons, imagery. - Automation-friendly structure: stable deep-link anchors, data-* hooks on every specimen, an embedded machine-readable token export (getComputedStyle, never drifts; optional /brand.json), and stable semantic DOM for visual-regression. - Always-on essentials: light/dark toggle, accessibility note, discreet link. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…r taxonomy Specify exactly how the user picks collateral, and broaden the menu: - Selection mechanism (in the upfront intake): a multiSelect "what should /brand deliver beyond the core guide?" (brand/press kit, marketing collateral), then — if collateral — a multiSelect of four buckets, with the auto "Other" option capturing the long tail (AskUserQuestion caps a question at four options). Confirm platforms/sizes/formats per chosen group. - Four selectable buckets, each with concrete items and the right output formats: Social & web (per-platform sizes, OG cards, IAB ad sizes); Email (React Email, tested clients); Print (print-ready CMYK PDFs, bleed/crop); Presentations & documents (editable pptx/Slides, pitch deck, one-pager, doc templates). - Long-tail groups behind "Other": Motion & video, Merch & environmental, Product & app-store, Audio & bespoke. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Stickers already live in the Print group; add podcast cover art to Social & web and drop the now-duplicate mention from the Audio long-tail item. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…s kit Give the brand/press kit the same depth as Tier 1/3: a comprehensive, external- facing kit that is both a human page and a machine endpoint. - Contents: full logo suite (variants/formats), favicon set, color (hex/oklch/ rgb/cmyk/pantone + .ase + JSON), typography spec, a PDF brand book, boilerplate copy (short/medium/long), imagery, links and a usage license. - Packaging: a stable brand-kit.zip with a sane folder layout, plus a human press-kit page that previews and links everything (Tier 1 anchors + data-*). - Automation endpoint: a /brand/kit.json manifest (version, assets with per- format URLs, color set, fonts+licenses, boilerplate, links, contact), stable versioned asset URLs, and a CORS note. Internal token truth (Tier 1 #brand-tokens) vs external asset truth (this manifest). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…racking Audit pass on SKILL.md as the orchestrator: - Fix step ordering: "Detect first" and "Gather decisions up front" sat above the Procedure even though they must run AFTER ingest (the intake text even assumes the intent was already read). Fold ingest -> detect -> decide into a single ordered Phase 0 so reading order matches execution order. Phases 1-7 and every reference's phase-number citation stay valid. - Gates: go from three to four explicit, phase-mapped, evidence-bearing gates — (1) static contrast [Phase 2], (2) licensing [Phase 4], (3) verification [Phase 5, now incl. rendered contrast + responsive + cross-browser], and (4) sign-off [Phase 6]. Rename the Phase 5 heading to match. - Chat tracking: strengthen the Definition of Done so the agent posts the checklist to the chat up front, ticks it as phases complete, and reports each gate's PASS with evidence (numbers, screenshots, the user's approval) before taking the guarded action — completion criteria stay visible in the conversation, not buried in the file. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…f verify Playwright's usage was documented but its setup wasn't — inconsistent with how the skill provisions its other gates, and broken for greenfield repos that have no Playwright at all. Now handled end to end: - Detect & provision: if @playwright/test is missing, install it + run `npx playwright install` + write playwright.config.ts (the same provisioning stance the skill takes for check-contrast.mjs and the Taskfile tasks). - Add a `verify:browsers` task to Taskfile.design.yml (Playwright sweep across Chromium/Firefox/WebKit × devices) so the cross-engine check runs like the other gates; wire it into the Phase 5 task list. - Fallback rule: agent-browser is Chromium-only and does NOT satisfy the cross-engine half of gate ③; if Playwright/cloud lab truly can't run, flag the gap to the user rather than reporting the cross-browser gate as PASS. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ship the cross-browser sweep as a reusable template rather than making the agent write it from scratch each run — the matrix/iteration logic is stable and easy to get subtly wrong, while only a few inputs truly vary per project. - assets/brand-screenshots.spec.ts: a parameterized harness. Engine × device comes from playwright.config.ts `projects`; the spec adds route × theme and writes one full-page PNG per route × theme per project. Three marked fill-ins: ROUTES, baseURL/webServer, and setTheme() (defaults to shadcn's .dark class). Includes a commented per-specimen capture using the data-brand-specimen hooks. - Add `use.baseURL` + `webServer` to the config example so the spec runs. - Wire it through: verify:browsers runs it; documented in responsive-and-cross-browser.md and listed in SKILL.md's bundled assets. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…andoff Make the skill handle three use cases as first-class modes, and make ingestion format-agnostic — without redesigning what's already there. - Three modes (establish / evolve / implement-feature), detected in Phase 0 (ask if ambiguous) and routed in Phase 2. The intro, Definition of Done, Phase 1/2, and Guardrails now reflect them. - Drift governance / anti-clobber doctrine: the bundle is a PROPOSAL, the repo is truth. Never overwrite globals.css wholesale; diff against canonical; new tokens are a decision point (force-fit vs. deliberate additive extension); record system changes as a DDR with a SemVer bump. This protects an established system when a feature handoff re-emits drifted tokens. - New reference evolving-the-system.md: token diff (added/changed/removed), SemVer classification, aliasing + deprecation for breaking changes, the DDR record, and /brand as the regression surface. - token-reconciliation.md gains a consume-first section (diff/map/decision-point + OKLCH closeness tolerance); ingesting-the-bundle.md gains a defensive, format-agnostic section (proprietary unstable format; parse for intent; also fits other tools like Google Stitch). Keep DDR (repo convention), not the research's PDR term. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…-system Make the system-vs-feature distinction explicit in the mode names: establish -> establish-design-system, evolve -> evolve-design-system. implement-feature is already clear and unchanged. Prose verbs/titles and the evolving-the-system.md filename are untouched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Distill the implementation-relevant slice of a design-deliverables master list into one lean, on-demand reference — a completeness self-check (not a build mandate) the agent consults in establish-design-system / evolve-design-system and when building /brand, so it doesn't miss a token category, component family, or brand asset (e.g. chart palette, gradients, named z-index layers, named animations, OG images). - New references/deliverables-checklist.md: terse, pointer-based coverage list that links to the detailed references rather than re-explaining them; plus a "scoped OUT" section (page/screen catalog, UX-process artifacts, marketing production) noting those belong to the separate Claude Design *creation* skill. - Wire it in: SKILL.md reference index + a Phase 1 pointer; one-line pointers from greenfield-bootstrap.md, brand-page.md (Foundations), and evolving-the-system.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…reenfield-bootstrap Surround the in-list `ts` Vite-config block with blank lines so it satisfies markdownlint MD031 (blanks-around-fences). The fence stays indented under the list item, so the list structure is unchanged. Pre-existing nit unrelated to the skill's logic. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…hree) Align with SKILL.md's four-gate model: the intro now says this file covers gates 3 (Verification, Phase 5) and 4 (Sign-off, Phase 6), with 1 (static contrast, Phase 2) and 2 (licensing, Phase 4) upstream. The recap lists all four numbered gates and marks Phase 7 close-out as post-gate actions, not a gate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… three modes Consistency pass found ingesting-the-bundle.md's 'After ingest' step still used the retired two-path model. Point it at SKILL.md Phase 0's mode detection (establish-design-system / evolve-design-system / implement-feature) instead. Co-Authored-By: Claude Opus 4.8 (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.
What & why
Upgrades the
design-handoffskill (Claude Design → code) from a strong-but-dated single file into a comprehensive, AI-native skill, based on a deep-research pass into what Claude Design actually exports today.Corrected export model. No longer assumes
?v=Ncache-busted files, atask export:design/tokens.jsonpipeline, or screenshots in the bundle (all unverified/contradicted). It now targets the real "Handoff to Claude Code".tar.gz: README → chat transcript → prototype HTML/JSX/CSS +tokens.css/site.css+ uploads — prototype-grade code that gets ported into the repo's stack, not pasted.Greenfield + brownfield. Handles both reconciling into an existing design system and bootstrapping a new one (Tailwind v4 + shadcn init,
globals.css,/brand,docs/design/, Taskfile tasks), with per-framework recipes for TanStack Router, React Router/plain, and Astro 6 (React islands for shadcn).Structure. A lean (~220-line) phased, gated
SKILL.mdorchestrator + nine progressive-disclosurereferences/carrying the novice-facing "explain-why" depth.Bundled, self-contained gates.
assets/check-contrast.mjs— a zero-dependency OKLCH→WCAG static contrast checker (noculorineeded; runs on Node alone) — plusassets/Taskfile.design.ymlsnippets the skill merges into a target repo.Preserved the strong parts: role-based token mapping, the dual (static + rendered) contrast gate, the licensing gate, sign-off-before-deletion, and PR-not-merge.
Verification
check-contrast.mjstested: exit 0 (all AA pass) / 1 (sub-AA text pair) / 2 (error); OKLCH→luminance math matches hand calcs (white-on-black = 21:1).Taskfile.design.ymlparses under go-task 3.51.1.SKILL.mdis 221 lines (<250); every reference is cross-linked fromSKILL.md; frontmatter within limits.?v=/task export:design/ straytokens.json/ known typos remain.Notes
SKIP=ansible-lintonly — the repo'sansible-linthook crashes on import (v6.22.2 vs Python 3.14) and currently blocks all commits; this change has no ansible content, and every other pre-commit hook ran and passed. Worth fixing that hook separately.ai/skills/README.md(the roadmap the/brandcollateral tiers reference) is untracked locally and intentionally left out of this PR — commit it separately if you want that reference resolved in-repo.🤖 Generated with Claude Code