docs(skills): point design-handoff at specs/ and new docs paths

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-<feature>/`. If you can't find one, ask
+- A handoff bundle, usually unpacked to `specs/handoff-<feature>/`. 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-<feature>/` (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-<feature>/` (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

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:

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

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

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

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 <bundle>.tar.gz -C docs/design/        # or: task ingest:design BUNDLE=<bundle>.tar.gz
+tar -xzf <bundle>.tar.gz -C specs/        # or: task ingest:design BUNDLE=<bundle>.tar.gz
 ```
 
-It extracts to a single project directory. Move/rename it to `docs/design/handoff-<feature>/`.
+It extracts to a single project directory. Move/rename it to `specs/handoff-<feature>/`.
 
 ## 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-<feature>/` **untouched**: it is the reference the
+system). Leave the bundle in `specs/handoff-<feature>/` **untouched**: it is the reference the
 user signs off against in Phase 6 and is not removed until Phase 7, after explicit approval.

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-<feature>/` so a stale runnable
+1. **Delete the bundle.** Once approved, delete `specs/handoff-<feature>/` 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