From c5c2219e703f2a43f5da3bba361200aa32b57e09 Mon Sep 17 00:00:00 2001 From: Evan Harmon Date: Mon, 22 Jun 2026 20:28:21 -0500 Subject: [PATCH] docs(skills): point design-handoff at specs/ and new docs paths Update the design-handoff skill to match the revised handoff process and doc taxonomy: - Handoff bundle now lands in/is deleted from `specs/` instead of `docs/design/` (SKILL.md, ingesting-the-bundle.md, verification-and-signoff.md, Taskfile.design.yml ingest:design default DEST). - Persistent human design docs consolidated from the `docs/design/` folder into a single `docs/architecture/design-language.md` (visual + UX = architecture). - DDR references aligned from bare `/decisions/` to `docs/decisions/`. Root `DESIGN.md` (AI-facing intent) is intentionally left in place. Co-Authored-By: Claude Opus 4.8 (1M context) --- ai/skills/design/design-handoff/SKILL.md | 14 +++++++------- .../design-handoff/assets/Taskfile.design.yml | 4 ++-- .../references/ethics-and-licensing.md | 2 +- .../references/evolving-the-system.md | 2 +- .../references/greenfield-bootstrap.md | 6 +++--- .../references/ingesting-the-bundle.md | 8 ++++---- .../references/verification-and-signoff.md | 12 ++++++------ 7 files changed, 24 insertions(+), 24 deletions(-) diff --git a/ai/skills/design/design-handoff/SKILL.md b/ai/skills/design/design-handoff/SKILL.md index 82c5de8..2a1197c 100644 --- a/ai/skills/design/design-handoff/SKILL.md +++ b/ai/skills/design/design-handoff/SKILL.md @@ -91,15 +91,15 @@ Gates — post **PASS + evidence** in the chat before taking the guarded action Close-out (only once gate ④ is green) - [ ] Handoff bundle deleted (or a thin screenshot + intent note extracted first if states remain) -- [ ] `docs/design/` and `/brand` updated; a system change recorded as a **DDR with a SemVer bump** +- [ ] `docs/architecture/design-language.md` and `/brand` updated; a system change recorded as a **DDR with a SemVer bump** - [ ] Conventional Commit on a **feature branch**; PR opened for human review; hooks never bypassed (`--no-verify` prohibited); no direct merge to `main` ## Inputs & stack -- A handoff bundle, usually unpacked to `docs/design/handoff-/`. If you can't find one, ask +- A handoff bundle, usually unpacked to `specs/handoff-/`. If you can't find one, ask the user where the export landed (or whether they've exported yet) before proceeding. -- The existing repo: `DESIGN.md` (root), `src/styles/globals.css`, `docs/design/`, `Taskfile.yml`, and +- The existing repo: `DESIGN.md` (root), `src/styles/globals.css`, `docs/architecture/design-language.md`, `Taskfile.yml`, and the project's `CLAUDE.md`. - **Stack target:** TypeScript, React, Vite, pnpm, Tailwind CSS v4, shadcn/ui, Lucide, Cloudflare Pages/Workers. Named primary router **TanStack Router**; **React Router**/plain React and **Astro 6** @@ -124,7 +124,7 @@ All the up-front orientation happens here, before any building: whatever is actually present in that spirit (intent/README → transcript → markup → tokens → assets), and adapt if a piece is named or shaped differently. The prototype code is prototype-grade — read it for structure and intent, then **port** it; don't paste markup into `src/`. Locate the bundle (often - `docs/design/handoff-*/`); if you can't find it, ask where the export landed. (`ingesting-the-bundle.md`) + `specs/handoff-*/`); if you can't find it, ask where the export landed. (`ingesting-the-bundle.md`) 2. **Detect mode, framework & router.** **Mode** — `establish-design-system` (no design system: no real `:root` tokens in `globals.css` and no `/brand` route), `evolve-design-system` (a system exists and the bundle is token/brand-dominant, or intent says "update the design system"), or `implement-feature` (a system @@ -147,7 +147,7 @@ All the up-front orientation happens here, before any building: If detection found no design system, stand one up before reconciling: install and configure Tailwind v4 and shadcn for the detected framework, let `shadcn init` write the default three-layer `globals.css`, -scaffold the `/brand` route, `DESIGN.md`, and `docs/design/`, copy `scripts/check-contrast.mjs`, and add +scaffold the `/brand` route, `DESIGN.md`, and `docs/architecture/design-language.md`, copy `scripts/check-contrast.mjs`, and add the design Taskfile tasks. **Normalize whatever the bundle emits** (often HSL or inline values) into the canonical OKLCH three-layer form, and record a **DDR establishing the system at v1.0.0**. Assumes a working frontend app already exists. Use `deliverables-checklist.md` to confirm the **full** token and @@ -215,8 +215,8 @@ the user explicitly approves.** The bundle stays fully in place through this ste ### Phase 7 — Close out (only after approval) -Delete `docs/design/handoff-/` (or extract a thin screenshot + intent note first if states -remain), update `docs/design/` and `/brand`, and record a **DDR (with a SemVer bump)** in `/decisions/` +Delete `specs/handoff-/` (or extract a thin screenshot + intent note first if states +remain), update `docs/architecture/design-language.md` and `/brand`, and record a **DDR (with a SemVer bump)** in `docs/decisions/` for any design-system change — `establish-design-system` (v1.0.0), `evolve-design-system` (patch/minor/major), or a feature token extension. Commit with Conventional Commits on a **feature branch** (direct commits to `main` are blocked) and open a **PR** for human review — never merge to `main` directly. See diff --git a/ai/skills/design/design-handoff/assets/Taskfile.design.yml b/ai/skills/design/design-handoff/assets/Taskfile.design.yml index 5d81243..dee8a21 100644 --- a/ai/skills/design/design-handoff/assets/Taskfile.design.yml +++ b/ai/skills/design/design-handoff/assets/Taskfile.design.yml @@ -28,9 +28,9 @@ tasks: src 2>/dev/null ingest:design: - desc: Decompress a Claude Design handoff .tar.gz into docs/design/ + desc: Decompress a Claude Design handoff .tar.gz into specs/ vars: - DEST: '{{.DEST | default "docs/design"}}' + DEST: '{{.DEST | default "specs"}}' requires: vars: [BUNDLE] cmds: diff --git a/ai/skills/design/design-handoff/references/ethics-and-licensing.md b/ai/skills/design/design-handoff/references/ethics-and-licensing.md index 1b5c809..612685f 100644 --- a/ai/skills/design/design-handoff/references/ethics-and-licensing.md +++ b/ai/skills/design/design-handoff/references/ethics-and-licensing.md @@ -66,7 +66,7 @@ the user chooses consciously, and record genuine decisions as a **DDR** (see is just CSS. These are conscious tradeoffs, not blockers. A genuine, debatable choice (a backend, a token -architecture, a palette-philosophy shift) warrants a DDR in `/decisions/` — not prose buried in +architecture, a palette-philosophy shift) warrants a DDR in `docs/decisions/` — not prose buried in `DESIGN.md`. ## The gate diff --git a/ai/skills/design/design-handoff/references/evolving-the-system.md b/ai/skills/design/design-handoff/references/evolving-the-system.md index c68bbd6..c072e98 100644 --- a/ai/skills/design/design-handoff/references/evolving-the-system.md +++ b/ai/skills/design/design-handoff/references/evolving-the-system.md @@ -44,7 +44,7 @@ Treat tokens like API endpoints — version, alias, and deprecate slowly: ## 4. Record a DDR with the version bump -Every system change is a **DDR** in `/decisions/` — your design-system changelog and governance trail. +Every system change is a **DDR** in `docs/decisions/` — your design-system changelog and governance trail. A token-change DDR carries: a unique ID (e.g. `DDR-0xx`), status, context (why the change), the decision (the exact token delta), alternatives considered, consequences (which components are affected, what migration is needed), and the resulting **SemVer bump**. DDRs are append-only (the ADR tradition) — if a diff --git a/ai/skills/design/design-handoff/references/greenfield-bootstrap.md b/ai/skills/design/design-handoff/references/greenfield-bootstrap.md index a79ad17..b9ac057 100644 --- a/ai/skills/design/design-handoff/references/greenfield-bootstrap.md +++ b/ai/skills/design/design-handoff/references/greenfield-bootstrap.md @@ -24,7 +24,7 @@ existing `globals.css` (`token-reconciliation.md`). 2. A starter `src/styles/globals.css` in shadcn three-layer OKLCH form (default neutral tokens — Phase 2 replaces the _values_ with the design's). 3. A `/brand` route stub (filled in during Phase 3 — see `brand-page.md`). -4. `DESIGN.md` (root, AI-facing intent) and `docs/design/` human docs. +4. `DESIGN.md` (root, AI-facing intent) and `docs/architecture/design-language.md` human docs. 5. The design Taskfile gates: `scripts/check-contrast.mjs` copied in, and `lint:design` / `ingest:design` merged into `Taskfile.yml`. @@ -92,8 +92,8 @@ pnpm dlx shadcn@latest init # configures components.json + path alia palette, type scale, spacing, radii, component rules, and the prose "do's and don'ts" tokens can't capture. Phase 2/3 fill it from the design; `globals.css` wins for _runtime_ values, `DESIGN.md` carries _intent_. -- **`docs/design/`** — human-facing docs: `brand.md`, `design-system.md`, `components.md`, - `accessibility.md`, `ux.md`. Stubs are fine now; they grow as the design lands. +- **`docs/architecture/design-language.md`** — the human-facing visual + UX design language (brand, + design system, components, accessibility, UX). A stub is fine now; it grows as the design lands. - **`/brand`** — create the route stub now; build it out in Phase 3 (`brand-page.md`). ## Wire the quality gates diff --git a/ai/skills/design/design-handoff/references/ingesting-the-bundle.md b/ai/skills/design/design-handoff/references/ingesting-the-bundle.md index 02c1b16..f265b12 100644 --- a/ai/skills/design/design-handoff/references/ingesting-the-bundle.md +++ b/ai/skills/design/design-handoff/references/ingesting-the-bundle.md @@ -19,13 +19,13 @@ the bundle treated as a proposal. "Handoff to Claude Code" produces a **gzipped tarball** (`.tar.gz`, served as `application/gzip`) — **not** a `.zip`. (Claude Design's separate "Download as .zip" menu item is a different raw-assets -export; the coding handoff is the tarball.) Decompress it into the repo's design folder: +export; the coding handoff is the tarball.) Decompress it into the repo's `specs/` folder: ```bash -tar -xzf .tar.gz -C docs/design/ # or: task ingest:design BUNDLE=.tar.gz +tar -xzf .tar.gz -C specs/ # or: task ingest:design BUNDLE=.tar.gz ``` -It extracts to a single project directory. Move/rename it to `docs/design/handoff-/`. +It extracts to a single project directory. Move/rename it to `specs/handoff-/`. ## Anatomy (verified, current as of mid-2026) @@ -90,5 +90,5 @@ Inventory what you got — the `tokens.css` palette/scales, the component list u referenced, the `uploads/` — then **detect the framework, router, and mode** (SKILL.md Phase 0): `establish-design-system` (no system yet — `greenfield-bootstrap.md`), `evolve-design-system` (changing the system — `evolving-the-system.md`), or `implement-feature` (a feature against an existing -system). Leave the bundle in `docs/design/handoff-/` **untouched**: it is the reference the +system). Leave the bundle in `specs/handoff-/` **untouched**: it is the reference the user signs off against in Phase 6 and is not removed until Phase 7, after explicit approval. diff --git a/ai/skills/design/design-handoff/references/verification-and-signoff.md b/ai/skills/design/design-handoff/references/verification-and-signoff.md index 6ab5d9b..605b0d5 100644 --- a/ai/skills/design/design-handoff/references/verification-and-signoff.md +++ b/ai/skills/design/design-handoff/references/verification-and-signoff.md @@ -53,18 +53,18 @@ against. ## Phase 7 — Close out (only after explicit approval) -1. **Delete the bundle.** Once approved, delete `docs/design/handoff-/` so a stale runnable +1. **Delete the bundle.** Once approved, delete `specs/handoff-/` so a stale runnable snapshot can't later mislead an agent into treating it as a source of truth. The one exception: if the design includes states not yet built, extract a _thin_ screenshot + intent note into the relevant spec first, then delete the rest. The durable records are the merged code, `DESIGN.md`/`globals.css`, `/brand`, and any DDR. -2. **Update the docs.** `docs/design/` (`brand.md`, `design-system.md`, `components.md`, - `accessibility.md`, `ux.md`) and the `/brand` page whenever brand-level things changed — keep them - in lockstep with `DESIGN.md`/`globals.css`. Update `README.md` if new scripts or usage were - introduced. +2. **Update the docs.** `docs/architecture/design-language.md` (the visual + UX design language — + brand, design system, components, accessibility, UX) and the `/brand` page whenever brand-level + things changed — keep them in lockstep with `DESIGN.md`/`globals.css`. Update `README.md` if new + scripts or usage were introduced. 3. **Flag decisions.** If the design embodied a genuine, debatable design-system decision (a new token architecture, a palette-philosophy shift, a vendor choice), tell the user it warrants a **DDR** in - `/decisions/`. Architecture decisions don't belong in this skill or in `DESIGN.md` prose — they + `docs/decisions/`. Architecture decisions don't belong in this skill or in `DESIGN.md` prose — they belong in a decision record. 4. **Commit & PR.** Use **Conventional Commits**. Commit on a **feature branch** — direct commits to `main` are blocked and wrong. The agent **never merges to `main` directly**: open a **PR** for human